New API features in Archicad 30

New API features in Archicad 30

This outline summarizes the major new features and changes in the API available with Archicad 30.

System requirements changes

Technical changes

New functionality

• The witness extension lines of dimensions can now have different pen and line type from the dimension line. These attributes are stored in the API_DimElem structure, and can be set through the following variables:
  • witnessOverrideExtension: enable the use of overridden attributes
  • witnessExtensionLinePen: the pen of the witness extension line
  • witnessExtensionLineType: the line type of the witness extension line
• The default values of these attributes are stored in the API_DimensionType structure, in the defWitnessOverrideExtension, defWitnessExtensionLinePen, and defWitnessExtensionLineType variables.
• A gap can now be inserted between witness lines and their extension lines. This can be set using the following variables found in the API_DimElem structure:
  • witnessExtensionGap: enable the use of gap
  • witnessExtensionGapSize: the size of the gap between the witness line and the extension line
• The default values of these attributes are stored in the API_DimensionType structure, in the defWitnessExtensionGap and defWitnessExtensionGapSize variables.
• A new HTTPClient module has been released for efficient and compact coding HTTP requests.
• A new view image export API has been added:
  • ACAPI_View_GetCurrentImage (NewDisplay::NativeImage&, const API_ImageSource&) can retrieve image data from the current 3D or rendering view.
  • API_ImageSource enum has been introduced with image source options for 3D window and rendering window.
• The ACAPI.hpp umbrella header now includes the MEP electrical API headers for electrical circuits, devices, device defaults, panels, panel defaults, and project settings.
• A new Project Info management API has been added, allowing add-ons to manage Project Info groups and fields:
  • Groups can be created, renamed, deleted, reordered, and enumerated.
  • Fields can be created, renamed, deleted, moved between groups, and their values can be read and written.
  • Some fields are fixed (built-in) and cannot be renamed or deleted. Some fields have subfields whose values contribute to a parent field's calculated value; subfields cannot be moved independently, and the parent field's value cannot be set directly.
  • All modification functions respect Teamwork permissions for Project Info.

Modified/new structures

• API_DimensionType structure now has two new boolean variables: clipDimensionLine and clipWitnessLine, which replace the old clipOtherSide variable, and allow for separate line ending settings for the dimension line and witness lines.
• API_AddOnInfo structure now has a new version member, which can be used for displaying add-on version string on the info panel of the Add-On Manager dialog.
• API_PropertyMeasureType enum now has been extended with additional types, such as attribute index references, for better distinction of built-in properties.
• API_TextFrameShapeTypeID enum now has additional shape options: API_TextFrameShapeType_Diamond, API_TextFrameShapeType_Pointed_Rectangle90, API_TextFrameShapeType_Pointed_Rectangle120, API_TextFrameShapeType_Hexagon, and API_TextFrameShapeType_Hexagon_Rotated.
• API_CollisionElemResult member has been renamed from hasClearenceCollision to hasClearanceCollision.
• New API_AttributeCreationInfo structure holds creation metadata for an attribute: methodID (API_AttrCreationMethod enum), methodDescription, source, creatorUserName, and creation timestamp.
• New API_AttrCreationMethod enum identifies how an attribute was created (e.g. APIAttrCreationMethod_AddOn, APIAttrCreationMethod_Merge, APIAttrCreationMethod_Import, etc.).
• API_TWAccessRights enum has a new APICreationInfoClear value, which identifies the Teamwork permission to clear attribute creation information.
• New API_MenuItemDisabledByHostApplication flag (0x00000004) distinguishes menu items disabled by the host application from those disabled by an add-on.
• API_SurfaceTypeID enum value APISurfaceType_ColumnFisrt has been renamed to APISurfaceType_ColumnFirst to correct a typo.
• Publisher callback types and the PublishFormatMethods structure have changed:
  • SaveProc has been replaced by SaveWithOptionProc, and the saveProc member has been replaced by saveWithOptionProc.
  • New callback types SaveWithTranslatorProc, SaveTranslatorProc, and SaveInitialOptionProc support translator-based saving, translator selection, and initial save options.
  • New members saveWithTranslatorProc, saveTranslatorProc, and saveInitialOptionProc store these callbacks.

Modified/new functions

• ACAPI::MEP::PortBase changes:
  • New function named GetElemId: returns the Unique identifier of the PortBase object.
• ACAPI::MEP::ElementBase changes:
  • New function named GetPorts: queries MEP Elements' ports without having to get the ID first.
• ACAPI::MEP::ElementDefault changes:
  • New function named GetVentilationPortDefaults: collects every ventilation port default for a given element default.
  • New function named GetPipingPortDefaults: collects every piping port default for a given element default.
  • New function named GetCableCarrierPortDefaults: collects every cable carrier port default for a given element default.
  • New function named GetPortDefaults: collects every port default for a given element default, useful when you don't care about the domains of the ports.
• ACAPI_Element_GetPropertyObjects parameter changes: now using references and std::vector& instead of pointers and C arrays, the Int32* was removed, the new signature is const API_Elem_Head& , std::vector<API_PropertyObjectRefType>&.
• ACAPI_ElementLink_GetLinkedPropertyObjects parameter changes: now using references and std::vector& instead of pointers and C arrays, the new signature is const API_Elem_Head&, bool&, Int32&, std::vector<Int32>& (the last Int32* was removed).
• ACAPI_ElementLink_GetLinkedPropertyObjects and ACAPI_ElementLink_SetLinkedPropertyObjects functions: the parameter inviduallyLibInd (typo) has been renamed to individuallyLibInd in both the pointer-based overload and the new reference-based overload.
• ACAPI_LibraryManagement_UsableGDLString function: the str parameter type has been changed from const char* to const GS::UniString&.
• ACAPI_GeoLocation_CalcSunOnPlace function: the placeInfo parameter type has been changed from API_PlaceInfo* to API_PlaceInfo&.
• ACAPI_Element_GetElemTypeName returns the name of element type variation in case of subtype tools, rather than the parent element type.
• API_IView3DSettingsEventHandler has been introduced for being able to get notified on 3D view settings changes:
  • View3DSettingsChanged is called when 3D projection, filter and cut, or window settings change.
  • View3DSettingsChangedInNavigation is called during 3D navigation to track camera setting changes.
  • Avoid complex operations in these callbacks, as they can cause significant slowdowns.
  • API_IACEventNotifier has a new pure virtual function, NotifyView3DSettingsEvent, for dispatching these notifications. Implementations of this interface must implement the new function.
• ACAPI_Attribute_GetCreationInfo function: new function that retrieves creation metadata (API_AttributeCreationInfo) for an attribute identified by API_AttrTypeID and API_AttributeIndex, returned via std::optional<API_AttributeCreationInfo>&.
• ACAPI_Attribute_Create and ACAPI_Attribute_CreateExt functions: two new optional parameters have been added: API_AttrCreationMethod creationMethod (defaults to APIAttrCreationMethod_AddOn) and const GS::UniString& source (defaults to empty), allowing callers to specify how and from where the attribute originates.
• ACAPI_AutoText_CreateAnAutoText function: the second parameter has been renamed from uiKey to name.
• Publisher API changes:
  • ACAPI_AddOnIntegration_InstallPublisherSaveMethod has been replaced by separate save registration functions.
  • New ACAPI_AddOnIntegration_InstallPublisherSaveWithOptionMethod function can register save callback with options.
  • New ACAPI_AddOnIntegration_InstallPublisherSaveWithTranslatorMethod function can register save callback with selected translator.
  • New ACAPI_AddOnIntegration_InstallPublisherSaveTranslator function can register translator dialog callback.
  • New ACAPI_AddOnIntegration_InstallPublisherSaveInitialOption function can register initial options callback.
  • The DefaultTranslatorGetterProc callback parameter has been renamed from def to translator, without changing its type.
• New Graphical Override API functions for querying and applying the actually applied, visible override combination:
  • New function named ACAPI_GraphicalOverride_GetActualOverrideCombination: retrieves the override combination currently applied to the active window.
  • New function named ACAPI_GraphicalOverride_SetActualOverrideCombination: applies an override combination to the active window.
• New Project Info API functions:
  • New function named ACAPI_ProjectInfo_GetGroups: retrieves the GUIDs of all ProjectInfo groups in order.
  • New function named ACAPI_ProjectInfo_GetGroupName: retrieves the name of a ProjectInfo group by its GUID.
  • New function named ACAPI_ProjectInfo_CreateGroup: creates a new ProjectInfo group with the given name. Returns APIERR_NAMEALREADYUSED if the name is taken, APIERR_NOACCESSRIGHT if the user lacks Teamwork permission.
  • New function named ACAPI_ProjectInfo_RenameGroup: renames an existing ProjectInfo group. Returns APIERR_NAMEALREADYUSED if the new name is taken.
  • New function named ACAPI_ProjectInfo_DeleteGroup: deletes a ProjectInfo group. Returns APIERR_REFUSEDPAR if the group contains fixed fields.
  • New function named ACAPI_ProjectInfo_MoveGroup: moves a group to a new position. Pass std::nullopt for beforeGroupGuid to move to the end.
  • New function named ACAPI_ProjectInfo_GetFields: retrieves the GUIDs of all fields in a group, including subfields.
  • New function named ACAPI_ProjectInfo_GetField: retrieves the name and value of a field.
  • New function named ACAPI_ProjectInfo_CreateField: creates a new custom field in a group. Returns APIERR_NAMEALREADYUSED if the name is taken.
  • New function named ACAPI_ProjectInfo_RenameField: renames a custom field. Returns APIERR_REFUSEDPAR for fixed (built-in) fields.
  • New function named ACAPI_ProjectInfo_SetFieldValue: sets the value of a field. Returns APIERR_REFUSEDPAR if the field has subfields (its value is calculated automatically).
  • New function named ACAPI_ProjectInfo_DeleteField: deletes a custom field. Returns APIERR_REFUSEDPAR for fixed (built-in) fields.
  • New function named ACAPI_ProjectInfo_MoveField: moves a field to a new position, possibly in a different group. Returns APIERR_REFUSEDPAR for subfields. Pass std::nullopt for beforeFieldGuid to move to the end.

Deprecated functions and structures

These functions and structures are currently available, but they are intended to be removed in the future. They will not receive bug fixes and support.

• The CommunicationClient, CommunicationCommon and HTTP modules are not supported, considered as deprecated. Use the HTTPClient module module instead.
• ACAPI_GeoLocation_CalcSunOnPlace (API_PlaceInfo*) is deprecated, use ACAPI_GeoLocation_CalcSunOnPlace (API_PlaceInfo&).
• Pointer-based overloads of ACAPI_Element_GetPropertyObjects and ACAPI_ElementLink_GetLinkedPropertyObjects are deprecated, use the new reference + std::vector overloads.
• ACAPI_AutoText_CreateAnAutoText is deprecated, use ACAPI_ProjectInfo_CreateField instead.
• ACAPI_AutoText_DeleteAnAutoText is deprecated, use ACAPI_ProjectInfo_DeleteField instead.
• ACAPI_AutoText_SetAnAutoText is deprecated, use ACAPI_ProjectInfo_SetFieldValue instead. The new function identifies Project Info fields by their GUID rather than the legacy dbKey string. Field GUIDs can be queried via ACAPI_ProjectInfo_GetFields, and their current name and value can be retrieved using ACAPI_ProjectInfo_GetField. Starting from the next version, fields will no longer be accessible using the old dbKey-based identification.

Deleted functions and structures

• ACAPI_AddOnIntegration_InstallPublisherSaveMethod has been removed.
• SaveProc and PublishFormatMethods::saveProc have been removed. Use SaveWithOptionProc and PublishFormatMethods::saveWithOptionProc instead.
• The explicit API_ElemPartId::operator!= overload has been removed. The operator== overload remains available.
• Legacy Goodies identifiers APIAny_UsableGDLStringID and APIAny_CalcSunOnPlaceID have been removed. Use ACAPI_LibraryManagement_UsableGDLString and ACAPI_GeoLocation_CalcSunOnPlace directly instead.