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	APIMenuCommandProc(const API_MenuParams *menuParams)
	User supplied callback procedure for handling menu commands.

typedef GSErrCode	APIIOCommandProc(const API_IOParams *ioParams)
	User supplied callback procedure for handling I/O operations.

typedef GSErrCode	APIIO3DCommandProc(const API_IOParams *ioParams, Modeler::SightPtr sight)
	User supplied callback procedure for handling I/O operations.

typedef GSErrCode	APIPanelCreateProc(Int32 refCon, const void tabControl, void data, void **tabPage)
	Callback procedure for creating custom tabpages.

typedef GSErrCode	APIPanelDestroyProc(Int32 refCon, void *tabPage)
	Callback procedure for destroying custom tabpages.

typedef GSErrCode	APIESYMCommandProc(const API_ESYMParams *esymParams)
	User supplied callback function for handling external symbols.

typedef GSErrCode	APIModulCommandProc(GSHandle params, GSPtr resultData, bool silentMode)
	User supplied callback procedure for handling calls from other add-ons.

typedef GSErrCode	APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)
	Callback function to handle the different property assignments.

typedef GSErrCode	APISettingsCreateProc(void *uiData)
	Callback procedure for handle settings dialog create event.

typedef GSErrCode	APISettingsDestroyProc(void *uiData)
	Callback procedure for handle settings dialog destroy event.

typedef GSErrCode	APIPublishFormatCommandProc(void *uiData)
	Callback procedure for handle publish format command.

typedef GSErrCode	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	APIModulDataSaveOldFormatHandlerProc(API_FTypeID planFileType, GS::HashTable< GS::UniString, API_ModulData * > &modulesToSave)
	User supplied callback procedure for converting modules into previous format.

typedef GSErrCode	APIElemSetSaveOldFormatHandlerProc(API_FTypeID planFileType, GSConstPtr dataPtr, GSPtr *oldDataPtr)
	User supplied callback function for handling backward conversion on user data attached to elements.

typedef GSErrCode	APINavigatorAddOnViewPointDataMergeHandlerProc(const GS::Array< API_NavigatorAddOnViewPointData > &sourceVPDataArray)
	User supplied callback procedure for handling Navigator AddOn viewpoint merge operations.

typedef GSErrCode	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	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	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	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	APIPaletteControlCallBackProc(Int32 referenceID, API_PaletteMessageID messageID, GS::IntPtr param)
	User supplied callback function for handling special messages for modeless palettes.

Enumerations
enum	API_PropertyObjectCmdID { APIPropObj_None = 0 , APIPropObj_AssignProperty = 1 , APIPropObj_DisableProperty = 2 }
	The identifier of the command the handler was called for. More...

enum	API_ClassificationVisibilityMode { APIClassVis_IsEnabled = 0 , APIClassVis_IsClassificationVisible = 1 }
	Specifies what should the callback function return. More...

enum	API_PropertyVisibilityMode { APIPropVis_IsEnabled = 0 , APIPropVis_IsPropertyVisible = 1 }
	Specifies what should the callback function return. More...

enum	APIMenuCodeID { MenuCode_UserDef = 0 , MenuCode_File = 1 , MenuCode_Edit1 = 2 , MenuCode_Edit2 = 3 , MenuCode_Edit3 = 4 , MenuCode_Tools = 5 , MenuCode_Options1 = 6 , MenuCode_Options2 = 7 , MenuCode_Image = 8 , MenuCode_Calculate = 9 , MenuCode_TeamWork = 10 , MenuCode_Display = 11 , MenuCode_Palettes = 12 , MenuCode_Extras = 13 , MenuCode_Hotlink = 14 , MenuCode_GDLObjects = 15 , MenuCode_3DView = 16 , MenuCode_DocExtras = 17 , MenuCode_Interoperability = 18 , MenuCode_ModelCheck = 19 , MenuCode_Hidden = 20 , MenuCode_RoofExtras = 21 , MenuCode_Design = 22 , MenuCode_Help = 23 }
	Defines the menu where the add-on's menu command will appear. More...

enum	API_PanelType { APIPanel_None = 0 , APIPanel_Settings = 1 , APIPanel_Attribute = 2 , APIPanel_InfoBox = 3 }
	Defines the different types of panels in the Archicad interface. More...

Functions
GSErrCode	ACAPI_AddOnAddOnCommunication_RegisterSupportedService (GSType cmdID, Int32 cmdVersion)
	Registers a command which other add-ons can use.

GSErrCode	ACAPI_AddOnIntegration_RegisterRequiredService (const API_ModulID *modulID, GSType cmdID, Int32 cmdVersion)
	Check the availability of another add-on's command.

GSErrCode	ACAPI_MenuItem_RegisterMenu (short menuStrResID, short promptStrResID, APIMenuCodeID menuPosCode, GSFlags menuFlags)
	Registers the menu items of the add-on.

GSErrCode	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	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	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	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	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	ACAPI_LibraryPart_RegisterESYM (GSType signature, API_LibTypeID typeID, short stringResID)
	Registers an external symbol type with Archicad.

GSErrCode	ACAPI_Property_RegisterPropertyObjectHandler (short assignStrResID)
	Registers a property handler.

GSErrCode	ACAPI_AddOnIntegration_RegisterBuiltInLibrary (void)
	Registers built-in library parts to be loaded.

GSErrCode	ACAPI_AddOnIntegration_RegisterModulDataHandler (void)
	Registers the add-on to be called for merging and converting its module data.

GSErrCode	ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify classification visibility.

GSErrCode	ACAPI_Property_RegisterPropertyVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify property visibility.

GSErrCode	ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler (void)
	Registers the add-on to be called when Navigator AddOn viewpoints are merged, saved to an older format, or converted from an older format to the current format.

GSErrCode	ACAPI_AddOnIntegration_RegisterSettingsObserver (const API_ElemType &tool)
	Create an observer for an element settings dialog.

GSErrCode	ACAPI_AddOnIntegration_RegisterPublishFormat (const API_PublishFormatData &formatData)
	Registers a publish format which can be used in the publisher tree.

GSErrCode	ACAPI_AddOnIntegration_InstallModulCommandHandler (GSType cmdID, Int32 cmdVersion, APIModulCommandProc *handlerProc)
	Installs a callback to handle command calls from other add-ons.

GSErrCode	ACAPI_MenuItem_InstallMenuHandler (short menuStrResID, APIMenuCommandProc *handlerProc)
	Installs a callback procedure for handling the add-on's menu commands.

GSErrCode	ACAPI_AddOnIntegration_InstallFileTypeHandler (GSType cmdID, APIIOCommandProc *handlerProc)
	Installs a callback procedure for handling file operations.

GSErrCode	ACAPI_AddOnIntegration_InstallFileTypeHandler3D (GSType cmdID, APIIO3DCommandProc *handlerProc)
	Installs a callback procedure for handling file operations.

GSErrCode	ACAPI_AddOnIntegration_InstallPanelHandler (Int32 refCon, APIPanelCreateProc handlerCreateProc, APIPanelDestroyProc handlerDestroyProc)
	Installs the creation and destruction handlers for the registered custom settings panel.

GSErrCode	ACAPI_LibraryPart_InstallESYMHandler (GSType signature, APIESYMCommandProc *handlerProc)
	Installs a callback for handling external symbols.

GSErrCode	ACAPI_Property_InstallPropertyObjectHandler (short strResID, APIPropertyObjectCommandProc *propertyCommandProc)
	Installs the property handler function for the given menu item.

GSErrCode	ACAPI_AddOnIntegration_InstallModulDataMergeHandler (APIModulDataMergeHandlerProc *mergeHandlerProc)
	Installs a callback procedure for handling the module data merge operations.

GSErrCode	ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler (APIModulDataSaveOldFormatHandlerProc *modulDataSaveOldFormatProc)
	Installs a callback procedure for converting module data into an older format.

GSErrCode	ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler (APIElemSetSaveOldFormatHandlerProc *elemSetSaveOldFormatProc)
	Installs a callback procedure for handling the conversion of the user data, the add-on attached to an element set.

GSErrCode	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler (APINavigatorAddOnViewPointDataMergeHandlerProc *mergeHandlerProc)
	Installs a callback procedure for handling the Navigator AddOn viewpoint merge operations.

GSErrCode	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler (APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc *saveOldFormatProc)
	Installs a callback procedure for converting Navigator AddOn viewpoints into an older format.

GSErrCode	ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler (APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc *convertNewFormatProc)
	Installs a callback procedure for converting Navigator AddOn viewpoints into the current format.

GSErrCode	ACAPI_AddOnIntegration_InstallSettingsHandler (const API_ElemType &tool, APISettingsCreateProc handlerCreateProc, APISettingsDestroyProc handlerDestroyProc)
	Installs the create and destroy handlers for the registered settings observer.

GSErrCode	ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler (APIClassificationVisibilityHandlerProc *handlerProc)
	Installs the classification visibility handler function.

GSErrCode	ACAPI_Property_InstallPropertyVisibilityHandler (APIPropertyVisibilityHandlerProc *handlerProc)
	Installs the property visibility handler function.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherSaveWithOptionMethod (const char mimeType, SaveWithOptionProc saveWithOptionProc)
	Installs the save methods for the Publisher with the set options.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherSaveWithTranslatorMethod (const char mimeType, SaveWithTranslatorProc saveWithTranslatorProc)
	Installs the save methods for the Publisher with a selected translator.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherSaveOption (const char mimeType, SaveOptionProc saveOptionProc)
	Installs the option methods for the Publisher.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherSaveTranslator (const char mimeType, SaveTranslatorProc saveTranslatorProc)
	Installs the translator methods for the Publisher.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherSaveInitialOption (const char mimeType, SaveInitialOptionProc saveInitialOptionProc)
	Installs the option initializer methods for the Publisher.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherTranslatorGetter (const char mimeType, TranslatorGetterProc translatorGetterProc)

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherDefaultTranslatorGetter (const char mimeType, DefaultTranslatorGetterProc defaultTranslatorGetterProc)
	Installs the default translator getter function for the Publisher.

GSErrCode	ACAPI_AddOnIntegration_InstallPublisherFormatInfoGetter (const char mimeType, InfoGetterProc infoGetterProc)
	Installs the format info getter function for the Publisher.

void	ACAPI_KeepInMemory (bool keepIn)
	Instructs the host application to keep the add-on in memory after execution.

GSErrCode	ACAPI_RegisterModelessWindow (Int32 referenceID, APIPaletteControlCallBackProc *callBackProc, GSFlags controlFlags, const API_Guid &paletteGuid=APINULLGuid)
	Registers a modeless palette in the API.

GSErrCode	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 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 APIElemSetSaveOldFormatHandlerProc(API_FTypeID planFileType, GSConstPtr 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 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 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 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 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 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 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 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 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 the 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 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 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 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 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` or `APIPalMsg_GetPaletteDeactivationMethod`.

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 or navigates to a window where the palette should not be visible or closes the project. The value of the "param" parameter (really a bool*) is true if the current project has been closed. It the project is closed, then it is advised to destroy the palette, otherwise the palette should be hidden.

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.

APIPalMsg_GetPaletteDeactivationMethod

The API asks for the palette deactivation method, which can be the following:

API_PaletteDeactivationMethod enum
APIPaletteDeactivationMethod_Default	Disable palette items if it is docked before deactivation. Hide palette if it is undocked before deactivation.
APIPaletteDeactivationMethod_Hide	Hide palette when it is deactivated.
APIPaletteDeactivationMethod_DisableItems	Disable palette items when it is deactivated.

◆ APIPanelCreateProc

typedef GSErrCode 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 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 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 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 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 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 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.

Enumeration Type Documentation

◆ API_ClassificationVisibilityMode

enum API_ClassificationVisibilityMode

Specifies what should the callback function return.

Enumerator
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.

◆ API_PanelType

enum API_PanelType

Defines the different types of panels in the Archicad interface.

This enum specifies the types of panels that can be utilized in the Archicad interface for different purposes such as settings, attributes, and the infobox.

Enumerator
APIPanel_None	No panel type is selected.
APIPanel_Settings	Represents the settings panel where tool or object settings can be adjusted.
APIPanel_Attribute	Represents the attribute panel, which handles project attributes such as layers, line types, and materials.
APIPanel_InfoBox	Represents the infobox panel, a contextual toolbar that provides quick access to settings based on the active tool.

◆ API_PropertyObjectCmdID

enum API_PropertyObjectCmdID

The identifier of the command the handler was called for.

Enumerator
APIPropObj_None	None
APIPropObj_AssignProperty	Assign Property
APIPropObj_DisableProperty	Disable Property

◆ API_PropertyVisibilityMode

enum API_PropertyVisibilityMode

Specifies what should the callback function return.

Enumerator
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.

◆ APIMenuCodeID

enum APIMenuCodeID

Defines the menu where the add-on's menu command will appear.

Since: Archicad 26

Remarks: This structure is used in the ACAPI_MenuItem_RegisterMenu function.

Enumerator
MenuCode_UserDef	Add-on menu is configurable by the user.
MenuCode_File	Add-on commands will appear in the File menu after "Info".
MenuCode_Edit1	Add-on commands will appear in the Edit menu after "Find & Select".
MenuCode_Edit2	Add-on commands will appear in the Edit/Reshape submenu.
MenuCode_Edit3	Add-on commands will appear in the Edit/Move submenu.
MenuCode_Tools	Add-on commands will appear in the Options menu after the separator below layers.
MenuCode_Options1	Add-on commands will appear in the Options menu after "Show All Layers".
MenuCode_Options2	Add-on commands will appear at the bottom of the Options/Attributes submenu.
MenuCode_Image	Add-on commands will appear at the end of the Document/Creative Imaging submenu.
MenuCode_Calculate	Add-on commands will appear at the end of the Document/Schedules and Lists submenu.
MenuCode_TeamWork	Add-on commands will appear at the end of the Teamwork menu.
MenuCode_Display	Add-on commands will appear at the end of the View/Zoom submenu.
MenuCode_Palettes	Add-on commands will appear at the end of the Window/Palettes submenu.
MenuCode_Extras	Add-on commands will appear at the end of the Design/Design Extras submenu.
MenuCode_Hotlink	Add-on commands will appear in the File/External Content submenu.
MenuCode_GDLObjects	Add-on commands will appear in the File/Libraries and Objects submenu.
MenuCode_3DView	Add-on commands will appear in the Document/Set 3D View submenu.
MenuCode_DocExtras	Add-on commands will appear in the Document/Document Extras submenu.
MenuCode_Interoperability	Add-on commands will appear in the File/Interoperability submenu.
MenuCode_ModelCheck	Add-on commands will appear in the Design/Model Check submenu.
MenuCode_Hidden	Add-On Commands not displayed in the menu
MenuCode_RoofExtras	Add-on commands will appear in the Design/Roof Extras submenu.
MenuCode_Design	Add-on commands will appear in the Design menu.
MenuCode_Help	Add-on commands will appear in the Help menu.

Function Documentation

◆ ACAPI_ActivatePropertyObjectHandler()

GSErrCode 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 successfully.

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 {};

GSFlags flags;

mir.menuResID = menuResID;

mir.itemIndex = 1;

ACAPI_MenuItem_GetMenuItemFlags (&mir, &flags);

if (checkedAssignProperty)

flags = flags | API_MenuItemChecked;

else

flags = flags & !API_MenuItemChecked;

ACAPI_MenuItem_SetMenuItemFlags (&mir, &flags);

}

◆ ACAPI_AddOnAddOnCommunication_RegisterSupportedService()

GSErrCode ACAPI_AddOnAddOnCommunication_RegisterSupportedService	(	GSType	cmdID,
		Int32	cmdVersion )

Registers a command which other add-ons can use.

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 successfully.

Remarks: The function registers one of your add-ons' commands and makes it available for other add-ons. It should be called from the add-on's RegisterInterface function.

Example: //------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface (void)

{

GSErrCode err;

//

// Register command services

//

err = ACAPI_AddOnAddOnCommunication_RegisterSupportedService ('DWFO', 4L);

return err;

}

◆ ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler()

GSErrCode 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 successfully.

Remarks: This function should be called from the add-on's Initialize function after registering the classification handler with ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler.

Example: //------------------------------------------------------

// Called after the add-on has been loaded into memory

//------------------------------------------------------

GSErrCode APIMenuCommandProc_Main (const API_MenuParams *menuParams);

bool ClassificationVisibilityHandler (API_ClassificationVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& classificationItemGuid);

GSErrCode 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 ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler ( APIElemSetSaveOldFormatHandlerProc * elemSetSaveOldFormatProc )

Installs a callback procedure for handling the conversion of the user data, the add-on attached to an element set.

Parameters

elemSetSaveOldFormatProc [in] The callback function to handle the backward conversion

Returns

NoError - The function has completed successfully.

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 here to make it readable for the previous version.

◆ ACAPI_AddOnIntegration_InstallFileTypeHandler()

GSErrCode ACAPI_AddOnIntegration_InstallFileTypeHandler	(	GSType	cmdID,
		APIIOCommandProc *	handlerProc )

Installs a callback procedure for handling file operations.

Parameters

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

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

Example: // -----------------------------------------------------------------------------

// Called when the add-on has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize (void)

{

GSErrCode err = NoError;

err = ACAPI_AddOnIntegration_InstallFileTypeHandler (1, CustomAPIIOCommandProc);

return err;

}

◆ ACAPI_AddOnIntegration_InstallFileTypeHandler3D()

GSErrCode ACAPI_AddOnIntegration_InstallFileTypeHandler3D	(	GSType	cmdID,
		APIIO3DCommandProc *	handlerProc )

Installs a callback procedure for handling file operations.

Parameters

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

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

Example: // -----------------------------------------------------------------------------

// Called when the add-on has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize (void)

{

GSErrCode err = NoError;

err = ACAPI_AddOnIntegration_InstallFileTypeHandler3D (1, CustomAPIIO3DCommandProc);

return err;

}

◆ ACAPI_AddOnIntegration_InstallModulCommandHandler()

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

Installs a callback to handle command calls from other add-ons.

Parameters

cmdID	[in] An identifier of the command for which to install the callback procedure. You should use this 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. You should use this in the ACAPI_AddOnAddOnCommunication_RegisterSupportedService as the command version number in the RegisterInterface function.
handlerProc	[in] The callback function handles the command calls.

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 other add-ons want to use your add-on's supported services.

Example: // -----------------------------------------------------------------------------

// Called when the add-on has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize (void)

{

GSErrCode err = NoError;

err = ACAPI_AddOnIntegration_InstallModulCommandHandler ('DWFI', 1, CustomAPIModulCommandProc);

return err;

}

◆ ACAPI_AddOnIntegration_InstallModulDataMergeHandler()

GSErrCode ACAPI_AddOnIntegration_InstallModulDataMergeHandler ( APIModulDataMergeHandlerProc * mergeHandlerProc )

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

Parameters

mergeHandlerProc [in] The callback procedure that will handle the module data merge. It can be nullptr, which removes the installed callback.

Returns

NoError - The function has completed successfully.

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

◆ ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler()

GSErrCode ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler ( APIModulDataSaveOldFormatHandlerProc * modulDataSaveOldFormatProc )

Installs a callback procedure for converting module data into an 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 successfully.

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

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler()

GSErrCode ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler ( APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc * convertNewFormatProc )

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

Parameters

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

Returns

NoError - The function has completed successfully.

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

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler()

GSErrCode ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler ( APINavigatorAddOnViewPointDataMergeHandlerProc * mergeHandlerProc )

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

Parameters

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

Returns

NoError - The function has completed successfully.

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

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler()

GSErrCode ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler ( APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc * saveOldFormatProc )

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

Parameters

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

Returns

NoError - The function has completed successfully.

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

◆ ACAPI_AddOnIntegration_InstallPanelHandler()

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

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

Parameters

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

Returns

APIERR_REFUSEDPAR - No panel registered with refcon by the add-on.
NoError - The function has completed successfully.

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 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 successfully.

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

◆ ACAPI_AddOnIntegration_InstallPublisherFormatInfoGetter()

GSErrCode ACAPI_AddOnIntegration_InstallPublisherFormatInfoGetter	(	const char *	mimeType,
		InfoGetterProc *	infoGetterProc )

Installs the format info getter function for the Publisher.

Since: Archicad 27

Parameters

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

Returns

NoError - The function has completed successfully.

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

◆ ACAPI_AddOnIntegration_InstallPublisherSaveInitialOption()

GSErrCode ACAPI_AddOnIntegration_InstallPublisherSaveInitialOption	(	const char *	mimeType,
		SaveInitialOptionProc *	saveInitialOptionProc )

Installs the option initializer methods for the Publisher.

Parameters

mimeType	The unique mimeType which identifies the new publish format
saveInitialOptionProc	Callback function, called when initializing a new format

Returns

NoError - The function has completed with success.

Remarks: This function installs the callback functions for initializing the options of the new publish formats. The options are stored in API_Userdata structures. Example Refer to the Format Register Test example project of the API Development Kit.

◆ ACAPI_AddOnIntegration_InstallPublisherSaveOption()

GSErrCode 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 successfully.

Remarks: This function installs the callback functions for the new publish formats. The Add-on can create its 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_InstallPublisherSaveTranslator()

GSErrCode ACAPI_AddOnIntegration_InstallPublisherSaveTranslator	(	const char *	mimeType,
		SaveTranslatorProc *	saveTranslatorProc )

Installs the translator methods for the Publisher.

Parameters

mimeType	The unique mimeType which identifies the new publish format
saveTranslatorProc	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 translator dialog, the selected translator is stored in a API_TranslatorNameConfig structure. Example Refer to the Format Register Test example project of the API Development Kit.

◆ ACAPI_AddOnIntegration_InstallPublisherSaveWithOptionMethod()

GSErrCode ACAPI_AddOnIntegration_InstallPublisherSaveWithOptionMethod	(	const char *	mimeType,
		SaveWithOptionProc *	saveWithOptionProc )

Installs the save methods for the Publisher with the set options.

Parameters

mimeType	The unique mimeType which identifies the new publish format
saveWithOptionProc	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_InstallPublisherSaveWithTranslatorMethod()

GSErrCode ACAPI_AddOnIntegration_InstallPublisherSaveWithTranslatorMethod	(	const char *	mimeType,
		SaveWithTranslatorProc *	saveWithTranslatorProc )

Installs the save methods for the Publisher with a selected translator.

Parameters

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

Returns

NoError - The function has completed successfully.

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_InstallPublisherTranslatorGetter()

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

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 successfully.

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

◆ ACAPI_AddOnIntegration_InstallSettingsHandler()

GSErrCode 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] This callback function is called when the settings dialog is created.
handlerDestroyProc	[in] This callback function is called when the settings dialog is destroyed.

Returns

APIERR_BADPARS - No settings observer was registered for the settings dialog specified by the tool and variation.
NoError - The function has completed successfully.

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_RegisterAttributePanel()

GSErrCode 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 successfully.

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

◆ ACAPI_AddOnIntegration_RegisterBuiltInLibrary()

GSErrCode ACAPI_AddOnIntegration_RegisterBuiltInLibrary ( void )

Registers built-in library parts to be loaded.

Returns

NoError - The function has completed successfully.

Remarks: This function notifies the host application that your add-on has library parts compiled into it 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 Grid Tool add-on has its library part subtype. To compile the library part into the add-on module, the library part should be copied into the localized resource files of the add-on. and there must be a reference to it in the .GRC file:
'FILE' 133 "StairMaker Stair.gsm" {

"StairMaker Stair.gsm"

}

Registration in the RegisterInterface function:
//------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface ()

{

return ACAPI_AddOnIntegration_RegisterBuiltInLibrary ();

}

◆ ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler()

GSErrCode ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler ( void )

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

Returns

NoError - The function has completed successfully.

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

Example: //------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode 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;

}

◆ ACAPI_AddOnIntegration_RegisterFileType()

GSErrCode 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 identifying 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 successfully.

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 must call from your Initialize routine. The methodFlags parameter defines which dialog's 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 can also register the MIME type for the file. 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"), and 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:
'STR#' 32700 "File Type descriptions" {

/* [ 1] */ "DWF File"

/* [ 2] */ "model/vnd.dwf"

}

In the RegisterInterface function:
//------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface ()

{

return ACAPI_AddOnIntegration_RegisterFileType (1, 'GSAC', ' DWF', "dwf", 0, 32700, 0,

SaveAs2DSupported + Open2DSupported + Merge2DSupported + Import2DDrawingSupported);

}

◆ ACAPI_AddOnIntegration_RegisterInfoBoxPanel()

GSErrCode 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 successfully.

Remarks: This function appends a new panel to an element settings dialog specified by the tool. 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 the icon resource ID. For more details, refer to the general description of Custom Panels in Settings Dialogs.

◆ ACAPI_AddOnIntegration_RegisterModulDataHandler()

GSErrCode ACAPI_AddOnIntegration_RegisterModulDataHandler ( void )

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

Returns

NoError - The function has completed successfully.

Remarks: Call this function from RegisterInterface to let Archicad know that the add-on has APIModulDataMergeHandlerProc and/or APIModulDataSaveOldFormatHandlerProc callback functions implemented for merging and converting its modules. For these 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 ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler ( void )

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

Returns

NoError - The function has completed successfully.

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. For 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 ACAPI_AddOnIntegration_RegisterPublishFormat ( const API_PublishFormatData & formatData )

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

Parameters

formatData [in] Stores parameters of the new publish format

Returns

NoError - The function has completed successfully.

Remarks: For further information, read the documentation for the API_PublishFormatData structure.

Example: //------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode 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 ACAPI_AddOnIntegration_RegisterRequiredService	(	const API_ModulID *	modulID,
		GSType	cmdID,
		Int32	cmdVersion )

Check the availability of another 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 successfully.
APIERR_GENERAL - The service doesn't support the command.

Remarks: This function checks for the availability of another 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 add-on's RegisterInterface function.

Example: static constexpr API_ModulID otherAddonMDID = {0000000000, 000000000};

//------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface (void)

{

GSErrCode err;

//

// Register command services

//

err = ACAPI_AddOnIntegration_RegisterRequiredService (&otherAddonMDID, 'DWFO', 4L);

return err;

}

◆ ACAPI_AddOnIntegration_RegisterSettingsObserver()

GSErrCode ACAPI_AddOnIntegration_RegisterSettingsObserver ( const API_ElemType & tool )

Create an observer for 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 successfully.

Remarks: This function creates an observer for an element settings dialog specified by the tool. To get the 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 multiple 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 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 successfully.

Remarks: This function appends a new panel to an element settings dialog specified by tool and variation. 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. Please note that this function works only for non-hierarchical and MEP elements.

Example: Resources in the GRC file:
'STR#' 32550 "Panel test settings page" {

/* [ 1] */ "Panel test settings page"

}

'GDLG' 32701 TabPage 0 0 444 50 "Panel test settings page" {

/* [ 1] */ LeftText 0 3 80 18 LargePlain vCenter "Alternate Name:"

/* [ 2] */ TextEdit 84 4 136 16 LargePlain 15

/* [ 3] */ LeftText 0 28 50 18 LargePlain vCenter "U-Value:"

/* [ 4] */ RealEdit 84 29 40 16 LargePlain "0.0" "10.0"

/* [ 5] */ LeftText 224 28 50 18 LargePlain vCenter "Height:"

/* [ 6] */ LengthEdit 278 29 70 16 LargePlain "0.0" "1000000"

}

'DLGH' 32701 DLG_32701_Panel_Test_Settings_Page {

1 "" LeftText_0

2 "" TextEdit_0

3 "" LeftText_1

4 "" RealEdit_0

5 "" LeftText_2

6 "" LengthEdit_0

}

'GICN' 32650 "Settings page icon" {

"Panel_Icon"

}

Registration in the RegisterInterface function:
// -----------------------------------------------------------------------------

// Interface definitions

// -----------------------------------------------------------------------------

GSErrCode RegisterInterface ()

{

GSErrCode err = ACAPI_AddOnIntegration_RegisterSettingsPanel (1, API_WallID, 32650, 32550, 32701);

if (err != NoError) {

DBPRINTF ("Panel_Test add-on: Cannot register element settings panel\n");

}

return err;

}

◆ ACAPI_KeepInMemory()

void ACAPI_KeepInMemory ( bool keepIn )

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

Parameters

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

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, your add-on's Initialize and FreeData functions are not called. See more about this topic in the Tips and Tricks' Control the Load/Unload Mechanism section.

◆ ACAPI_LibraryPart_InstallESYMHandler()

GSErrCode 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 handles the creation and editing of the external symbol.

Returns

NoError - The function has completed successfully.

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 Initialize (void)

{

GSErrCode err = NoError;

err = ACAPI_LibraryPart_InstallESYMHandler ('ABCD', CustomAPIESYMCommandProc);

return err;

}

◆ ACAPI_LibraryPart_RegisterESYM()

GSErrCode 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 successfully.
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 RegisterInterface (void)

{

GSErrCode err;

// Register ESYM

err = ACAPI_LibraryPart_RegisterESYM ('GRPH', APILib_LampID, 32611);

return err;

}

◆ ACAPI_LibraryPart_RegisterSubtype()

GSErrCode 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 turn off 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 a subtype template.
NoError - The function has completed successfully.

Remarks

This function registers a new library part subtype. The add-on must contain a built-in library part in its resource module to have its element subtype. This library part will be loaded into the active libraries and becomes 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 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 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 in 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:
'FILE' 132 "Roof Opening.gsm" {

"Roof Opening.gsm"

}

'STR#' 32611 "Skylight subtype" {

/* [ 1] */ "Skylight" /* Subtype name */

/* [ 2] */ "Skylight Selection Settings..." /* Selection settings dialog title */

/* [ 3] */ "Select All Skylights" /* Select All menuitem string in Edit menu */

/* [ 4] */ "Skylight Tool" /* Toolbox item name */

/* [ 5] */ "The Skylight tool is used for placing skylight library items into roofs by clicking on the roof."

/* Toolbox item popup help text */

/* [ 6] */ "Skylight Default Settings..." /* Default settings dialog title */

/* [ 7] */ "Enter First Point of Skylight." /* Default prompt text */

}

'ACP0' 132 "Metric Defaults" {

/* [ 1] VarName */ "001_defObjName"

/* [ 1] Value */ "Skylight Pivot Hung"

/* [ 2] VarName */ "002_Symb_layer"

/* [ 2] Value */ "7"

/* [ 3] VarName */ "003_Symb_material"

/* [ 3] Value */ "47"

/* [ 4] VarName */ "004_Symb_info"

/* [ 4] Value */ "Sky-001"

/* [ 5] VarName */ "005_Symb_level"

/* [ 5] Value */ "0"

/* [ 6] VarName */ "006_Symb_pen"

/* [ 6] Value */ "2"

/* [ 7] VarName */ "007_Symb_onePen(0/1)"

/* [ 7] Value */ "0"

/* [ 8] VarName */ "008_Symb_showAlways"

/* [ 8] Value */ "0"

/* [ 9] VarName */ "009_Symb_showAbove"

/* [ 9] Value */ "0"

/* [ 10] VarName */ "010_Symb_showBelow"

/* [ 10] Value */ "0"

/* [ 11] VarName */ "011_Symb_gravityPar"

/* [ 11] Value */ "0"

/* [ 12] VarName */ "012_Symb_contourPen"

/* [ 12] Value */ "72"

/* [ 13] VarName */ "013_Symb_fillPen"

/* [ 13] Value */ "73"

/* [ 14] VarName */ "014_Symb_bkgPen"

/* [ 14] Value */ "80"

/* [ 15] VarName */ "015_Symb_fill"

/* [ 15] Value */ "65"

/* [ 16] VarName */ "016_Symb_lineType"

/* [ 16] Value */ "1"

/* [ 17] VarName */ "017_Symb_useLineType"

/* [ 17] Value */ "0"

/* [ 18] VarName */ "018_Symb_useMaterial"

/* [ 18] Value */ "1"

/* [ 19] VarName */ "019_Symb_useSectAttrs"

/* [ 19] Value */ "1"

/* [ 20] VarName */ "020_Symb_LightIsOn"

/* [ 20] Value */ "0"

/* [ 21] VarName */ "021_Symb_IsAutoOnStoryVisibility"

/* [ 21] Value */ "0"

}

In the RegisterInterface function:
//------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface ()

{

GSErrCode err = ACAPI_LibraryPart_RegisterSubtype ('SKLT', 132, true, 32611, 32602, 32603, TBoxGroup_Openings,

API_TBoxEnabled_FloorPlan + API_TBoxEnabled_ModelSection + API_TBoxEnabled_3D, 132);

return err;

}

◆ 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_Property_InstallPropertyObjectHandler()

GSErrCode 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 successfully.

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

Example: //------------------------------------------------------

// Called after the add-on has been loaded into memory

//------------------------------------------------------

GSErrCode Initialize (void)

{

ACAPI_MenuItem_InstallMenuHandler (32000, Callback_Check_AVA_OR_DIN_MenuItem);

ACAPI_Property_InstallPropertyObjectHandler (32500, Callback_Property);

return NoError;

}

◆ ACAPI_Property_InstallPropertyVisibilityHandler()

GSErrCode 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 successfully.

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 APIMenuCommandProc_Main (const API_MenuParams *menuParams);

bool PropertyVisibilityHandler (API_PropertyVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& propertyDefinitionGuid);

GSErrCode 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 ACAPI_Property_RegisterPropertyObjectHandler ( short assignStrResID )

Registers a property handler.

Parameters

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

Returns

NoError - The function has completed successfully.

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

Example: //------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode RegisterInterface (void)

{

ACAPI_MenuItem_RegisterMenu (MenuResId, MenuTextResId, MenuCode_Calculate, MenuFlag_Default);

ACAPI_Property_RegisterPropertyObjectHandler (PropertyResId);

return NoError;

}

◆ ACAPI_Property_RegisterPropertyVisibilityHandler()

GSErrCode ACAPI_Property_RegisterPropertyVisibilityHandler ( void )

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

Returns

NoError - The function has completed successfully.

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

Example: //------------------------------------------------------

// Interface definitions

//------------------------------------------------------

GSErrCode 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;

}

◆ ACAPI_RegisterModelessWindow()

GSErrCode 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 successfully.
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 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;

}

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ APIClassificationVisibilityHandlerProc

◆ APIElemSetSaveOldFormatHandlerProc

◆ APIESYMCommandProc

◆ APIIO3DCommandProc

◆ APIIOCommandProc

◆ APIMenuCommandProc

◆ APIModulCommandProc

◆ APIModulDataMergeHandlerProc

◆ APIModulDataSaveOldFormatHandlerProc

◆ APINavigatorAddOnViewPointDataConvertNewFormatHandlerProc

◆ APINavigatorAddOnViewPointDataMergeHandlerProc

◆ APINavigatorAddOnViewPointDataSaveOldFormatHandlerProc

◆ APIPaletteControlCallBackProc

◆ APIPanelCreateProc

◆ APIPanelDestroyProc

◆ APIPropertyObjectCommandProc

◆ APIPropertyVisibilityHandlerProc

◆ APIPublishFormatCommandProc

◆ APISettingsCreateProc

◆ APISettingsDestroyProc

Enumeration Type Documentation

◆ API_ClassificationVisibilityMode

◆ API_PanelType

◆ API_PropertyObjectCmdID

◆ API_PropertyVisibilityMode

◆ APIMenuCodeID

Function Documentation

◆ ACAPI_ActivatePropertyObjectHandler()

◆ ACAPI_AddOnAddOnCommunication_RegisterSupportedService()

◆ ACAPI_AddOnIntegration_InstallClassificationVisibilityHandler()

◆ ACAPI_AddOnIntegration_InstallElemSetSaveOldFormatHandler()

◆ ACAPI_AddOnIntegration_InstallFileTypeHandler()

◆ ACAPI_AddOnIntegration_InstallFileTypeHandler3D()

◆ ACAPI_AddOnIntegration_InstallModulCommandHandler()

◆ ACAPI_AddOnIntegration_InstallModulDataMergeHandler()

◆ ACAPI_AddOnIntegration_InstallModulDataSaveOldFormatHandler()

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataConvertNewFormatHandler()

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataMergeHandler()

◆ ACAPI_AddOnIntegration_InstallNavigatorAddOnViewPointDataSaveOldFormatHandler()

◆ ACAPI_AddOnIntegration_InstallPanelHandler()

◆ ACAPI_AddOnIntegration_InstallPublisherDefaultTranslatorGetter()

◆ ACAPI_AddOnIntegration_InstallPublisherFormatInfoGetter()

◆ ACAPI_AddOnIntegration_InstallPublisherSaveInitialOption()

◆ ACAPI_AddOnIntegration_InstallPublisherSaveOption()

◆ ACAPI_AddOnIntegration_InstallPublisherSaveTranslator()

◆ ACAPI_AddOnIntegration_InstallPublisherSaveWithOptionMethod()

◆ ACAPI_AddOnIntegration_InstallPublisherSaveWithTranslatorMethod()

◆ ACAPI_AddOnIntegration_InstallPublisherTranslatorGetter()

◆ ACAPI_AddOnIntegration_InstallSettingsHandler()

◆ ACAPI_AddOnIntegration_RegisterAttributePanel()

◆ ACAPI_AddOnIntegration_RegisterBuiltInLibrary()

◆ ACAPI_AddOnIntegration_RegisterClassificationVisibilityHandler()

◆ ACAPI_AddOnIntegration_RegisterFileType()

◆ ACAPI_AddOnIntegration_RegisterInfoBoxPanel()

◆ ACAPI_AddOnIntegration_RegisterModulDataHandler()

◆ ACAPI_AddOnIntegration_RegisterNavigatorAddOnViewPointDataHandler()

◆ ACAPI_AddOnIntegration_RegisterPublishFormat()

◆ ACAPI_AddOnIntegration_RegisterRequiredService()

◆ ACAPI_AddOnIntegration_RegisterSettingsObserver()

◆ ACAPI_AddOnIntegration_RegisterSettingsPanel()

◆ ACAPI_KeepInMemory()

◆ ACAPI_LibraryPart_InstallESYMHandler()

◆ ACAPI_LibraryPart_RegisterESYM()

◆ ACAPI_LibraryPart_RegisterSubtype()

◆ ACAPI_MenuItem_InstallMenuHandler()

◆ ACAPI_MenuItem_RegisterMenu()

◆ ACAPI_Property_InstallPropertyObjectHandler()

◆ ACAPI_Property_InstallPropertyVisibilityHandler()

◆ ACAPI_Property_RegisterPropertyObjectHandler()

◆ ACAPI_Property_RegisterPropertyVisibilityHandler()

◆ ACAPI_RegisterModelessWindow()