Attribute Management

Functions related to accessing and manipulating Attribute and the Attribute-related data of elements. More...

Classes
struct	API_LayerType
	Layer attribute representation. More...
struct	API_LineItems
	Describes the details of a symbol line. More...
struct	API_DashItems
	Describes one segment of a dashed line. More...
struct	API_LinetypeType
	Line type attribute representation. More...
struct	API_FillLine
	Describes the details of a vectorial fill. More...
struct	API_SFill_Line
	Describes a line item in a symbol fill. More...
struct	API_SFill_Arc
	Describes an arc item in a symbol fill. More...
struct	API_FilltypeType
	Fill type attribute representation. More...
struct	API_CWallComponent
	Describes the simple fills contained in composite structures. More...
struct	API_CWallLineComponent
	Describes the lines separate the simple fills contained in composite structures. More...
struct	API_CompWallType
	Composite fill attribute representation. More...
struct	API_LayerStat
	Describes one layer's characteristics in a layer combination. More...
struct	API_LayerCombType
	Layer combination attribute representation. More...
struct	API_ZoneCatType
	Zone category attribute representation. More...
struct	API_ProfileAttrType
	Attribute representing the custom profiles for walls, beams, and columns. More...
struct	API_PenTableType
	Pen table attribute. More...
struct	API_MEPSystemType
	MEP System attribute representation. More...
struct	API_HourlyProfile
	Describes coverage of an hour of an Operation Profile. More...
struct	API_DailyProfile
	Describes a daily profile contained in Operation Profile. More...
struct	API_DailyProfileUsage
	Describes a daily profile usage contained in Operation Profile. More...
struct	API_OperationProfileType
	An Energy Evaluation operation profile. More...
struct	API_BuildingMaterialType
	Building Material type attribute representation. More...
union	API_Attribute
	Describes the different attributes. More...
struct	API_SymbolHatchDef
	Describes the details of a symbol fill. More...
struct	API_AttributeDef
	Describes the extended information for different attributes. More...
struct	API_AttributeDefExt
	Describes the extended information for different attributes. More...
struct	API_AttributeFolder
	An attribute folder. More...
struct	API_AttributeFolderContent
	Content of an attribute folder. Contains direct subfolders and attributes. More...
struct	API_Pen
	Pen attribute representation. More...
class	API_AttributePickerParams
	Describes the type and the push check for creating an attribute picker in ACAPI_Dialog_CreateAttributePicker. More...
class	API_AttributePicker
	Describes an attribute picker created in ACAPI_Dialog_CreateAttributePicker, with getter and setter for the selected attribute and the hanlder of push check click event. More...
struct	API_AttributeFolderPickerParams
	Describes the type and the push check for creating an attribute folder picker in ACAPI_Attribute_CreateAttributeFolderPicker. More...
class	API_AttributeFolderPicker
	Describes an attribute folder picker created in ACAPI_Attribute_CreateAttributeFolderPicker, with getter and setter for the selected attribute folder and the hanlder of push check click event. More...

Typedefs
typedef GSErrCode __ACENV_CALL	APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)
	User supplied callback procedure for handling attribute replacements.
using	API_AttributeUserData = API_UserData
	A UserData attached to an Attribute.
typedef GS::HashTable< API_AttrTypeID, GS::HashTable< API_AttributeIndex, API_AttributeIndex > >	API_AttributeReplaceIndexTable
	Contains the deleted and replaced attribute indices grouped by attribute type.

Enumerations
enum	API_LtypItemID {   APILine_IllegalItemType , APILine_SeparatorItemType , APILine_CenterDotItemType , APILine_CenterLineItemType ,   APILine_DotItemType , APILine_RightAngleItemType , APILine_ParallelItemType , APILine_LineItemType ,   APILine_CircItemType , APILine_ArcItemType }
	Describes the various item types of a symbol line. More...
enum	API_OccupancyTypeID { APIOccupancyType_Residential = 1 , APIOccupancyType_NonResidential = 2 }
	Occupancy type of the Operation Profile.
enum	API_FillOrientationID { APIFillOrientation_ProjectOrigin = 0 , APIFillOrientation_ElementOrigin = 1 , APIFillOrientation_FitToSkin = 2 }
	Determines the orientation of the fill pattern.

Functions
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetCurrPenSet (API_AttributeIndex *penSetIndex)
	Get current pen set index.
GSErrCode __ACENV_CALL	ACAPI_AddOnIntegration_InstallAttrManagerImportMethod (const GS::UniString &fileExtension, ImportAttrProc *importProc)
	Installs the import method for the Attribute Manager.
GSErrCode __ACENV_CALL	ACAPI_DisposeAttrDefsHdls (API_AttributeDef *defs)
	Frees the memory occupied by all of the attribute definition handles.
GSErrCode __ACENV_CALL	ACAPI_DisposeAttrDefsHdlsExt (API_AttributeDefExt *defs)
	Frees the memory occupied by all of the attribute definition handles.
GSErrCode __ACENV_CALL	ACAPI_Attribute_ModifyPen (const API_Pen &pen)
	Modify a pen by index in the active pentable.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPen (API_Pen &pen)
	Returns a pen by index from the active pentable.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPenNum (UInt32 &count)
	Get the number of pens in the active pentable.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetNum (API_AttrTypeID typeID, UInt32 &count)
	Returns the number of instances of a given type of attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Get (API_Attribute *attribute)
	Retrieves an attribute from the database.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetAttributesByType (API_AttrTypeID typeID, GS::Array< API_Attribute > &attributes)
	Returns the instances of a given attribute type in the database.
GSErrCode __ACENV_CALL	ACAPI_Attribute_EnumerateAttributesByType (API_AttrTypeID typeID, const std::function< void(API_Attribute &)> &processor)
	Iterates the instances of a given attribute type in the database.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetDef (API_AttrTypeID typeID, API_AttributeIndex index, API_AttributeDef *defs)
	Retrieves extended information for an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetDefExt (API_AttrTypeID typeID, API_AttributeIndex index, API_AttributeDefExt *defs)
	Retrieves extended information for an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Create (API_Attribute *attribute, API_AttributeDef *defs)
	Creates an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_CreateExt (API_Attribute *attribute, API_AttributeDefExt *defs)
	Creates an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Modify (API_Attribute *attribute, API_AttributeDef *defs)
	Modifies an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_ModifyExt (API_Attribute *attribute, API_AttributeDefExt *defs)
	Modifies an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Search (API_Attr_Head *attrHead)
	Searches for an attribute by name.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Delete (const API_Attr_Head &attrHead)
	Deletes an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_DeleteMore (API_AttrTypeID attrTypeID, const GS::Array< API_AttributeIndex > &attrIndexList)
	Deletes more attributes of the same type.
GSErrCode __ACENV_CALL	ACAPI_UserData_GetUserData (API_Attr_Head *attrHead, API_AttributeUserData *userData)
	Obtains the user data attached to an attribute.
GSErrCode __ACENV_CALL	ACAPI_UserData_SetUserData (API_Attr_Head *attrHead, const API_AttributeUserData *userData)
	Attaches user data to an attribute, or deletes the attached data.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetAttributesFromProject (const IO::Location &location, API_AttrTypeID typeID, GS::Array< GS::Pair< API_Attribute, API_AttributeDefExt > > *resultArray)
	Loads the given attributes from a project file.
Modeler::IAttributeReader *__ACENV_CALL	ACAPI_Attribute_GetCurrentAttributeSetReader ()
	Returns an attribute reader for the currently used attribute set.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetFolder (API_AttributeFolder &folder)
	Retrieves an existing attribute folder by it's path or guid.
GSErrCode __ACENV_CALL	ACAPI_Attribute_CreateFolder (API_AttributeFolder &folder)
	Creates attribute folders. To create a folder, its full path has to be provided. The command will create all folders along the path, if they do not exist.
GSErrCode __ACENV_CALL	ACAPI_Attribute_Move (const GS::Array< API_AttributeFolder > &foldersToMove, const GS::Array< GS::Guid > &attributesToMove, const API_AttributeFolder &targetFolder)
	Moves attributes and attribute folders.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetFolderContent (const API_AttributeFolder &folder, API_AttributeFolderContent &result)
	Returns all folders and attributes of an attribute type.
GSErrCode __ACENV_CALL	ACAPI_Attribute_DeleteFolder (const API_AttributeFolder &folder)
	Deletes an attribute folder and all the folders and attributes it contains.
GSErrCode __ACENV_CALL	ACAPI_Attribute_RenameFolder (const API_AttributeFolder &folder, const GS::UniString &newName)
	Deletes an attribute folder and all the folders and attributes it contains.
GSErrCode __ACENV_CALL	ACAPI_Attribute_CreateAttributeFolderPicker (const API_AttributeFolderPickerParams &attributeFolderPickerParams, GS::Owner< API_AttributeFolderPicker > &attributeFolderPicker)
	Enables the attribute folder picker functionality for a push check, if the user clicks the push check, the picker will open. Attributes folder pickers can be used to choose an attribute folder.
API_AttributeIndex __ACENV_CALL	ACAPI_Attribute_GetFirstValidAttribute (API_AttrTypeID typeID)
	Returns the first valid attribute index.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetClassificationItems (const API_Attr_Head &attrHead, GS::Array< GS::Pair< API_Guid, API_Guid > > &systemItemPairs)
	Retrieves all of the classifications of an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetClassificationInSystem (const API_Attr_Head &attrHead, const API_Guid &systemGuid, API_ClassificationItem &item)
	Retrieves a classification of an attribute in a given classification system.
GSErrCode __ACENV_CALL	ACAPI_Attribute_AddClassificationItem (const API_Attr_Head &attrHead, const API_Guid &itemGuid)
	Classifies an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_RemoveClassificationItem (const API_Attr_Head &attrHead, const API_Guid &itemGuid)
	Removes a classification from an attribute.
bool __ACENV_CALL	ACAPI_Attribute_IsClassificationItemVisible (const API_Attr_Head &attrHead, const API_Guid &classificationGuid)
	Tells whether a classification item is visible for an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPropertyDefinitions (const API_Attr_Head &attrHead, API_PropertyDefinitionFilter filter, GS::Array< API_PropertyDefinition > &definitions)
	Retrieves all of the built-in property definitions that are available for an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPropertyValue (const API_Attr_Head &attrHead, const API_Guid &propertyDefinitionGuid, API_Property &property)
	Retrieves the property value of the property definition.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPropertyValues (const API_Attr_Head &attrHead, const GS::Array< API_PropertyDefinition > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the property values of the property definitions.
GSErrCode __ACENV_CALL	ACAPI_Attribute_GetPropertyValuesByGuid (const API_Attr_Head &attrHead, const GS::Array< API_Guid > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the property values of the property definitions.
GSErrCode __ACENV_CALL	ACAPI_Attribute_SetProperty (const API_Attr_Head &attrHead, const API_Property &property)
	Sets the property value of the property definition.
GSErrCode __ACENV_CALL	ACAPI_Attribute_SetProperties (const API_Attr_Head &attrHead, const GS::Array< API_Property > &properties)
	Sets the specified built-in properties for the given values on an attribute.
bool __ACENV_CALL	ACAPI_Attribute_IsPropertyDefinitionValueEditable (const API_Attr_Head &attrHead, const API_Guid &propertyGuid)
	Tells whether a property definition is editable for an attribute.
bool __ACENV_CALL	ACAPI_Attribute_IsPropertyDefinitionAvailable (const API_Attr_Head &attrHead, const API_Guid &propertyGuid)
	Tells whether a property definition is available for an attribute.
bool __ACENV_CALL	ACAPI_Attribute_IsPropertyDefinitionVisible (const API_Attr_Head &attrHead, const API_Guid &propertyGuid)
	Tells whether a property definition is visible for an attribute.
GSErrCode __ACENV_CALL	ACAPI_Attribute_AddProperty (API_PropertyDefinition &definition, const GS::Array< API_Attr_Head > &attrHeaders)
	Makes a property definition available for all of given attributes (it is created if it does not exist).
GSErrCode __ACENV_CALL	ACAPI_Attribute_ModifyPropertyValue (const API_Property &property, const GS::Array< API_Attr_Head > &attrHeaders)
	Sets the value of a property for multiple attributes. If the property is not available for at least one of the given attribute then returns with an error without changing any property value.
GSErrCode __ACENV_CALL	ACAPI_Attribute_DeleteProperty (const API_Guid &definitionGuid, const GS::Array< API_Attr_Head > &attrHeaders)
	Makes a property definition unavailable for all of given attributes.
GSErrCode __ACENV_CALL	ACAPI_Notification_CatchAttributeReplacement (APIAttributeReplacementHandlerProc *handlerProc)
	Register or unregister your add-on to be notified if some attributes are deleted and replaced by other attributes.
ADB::AttributeIndex	API2AC_AttrIndex (const API_AttributeIndex &apiIndex)
	Converts an API_AttributeIndex to ADB::AttributeIndex.
API_AttributeIndex	AC2API_AttrIndex (const ADB::AttributeIndex &acIndex)
	Converts an ADB::AttributeIndex to API_AttributeIndex.
API_AttributeIndex	ACAPI_CreateAttributeIndex (Int32 index)
	A wrapper function to create an API_AttributeIndex from its GS equivalent.

Detailed Description

Functions related to accessing and manipulating Attribute and the Attribute-related data of elements.

Attribute Overview

Available types of attributes are enumerated in the API_AttrTypeID structure. The definition of an attribute is described in the API_Attribute structure, which is in fact a union of all types of attributes. All of the attribute structures begin with a common header structure, named [APIAPI_Attr_Head

• The typeID field identifies the type of the attribute.
• The index field gives the current database index of the given attribute. References to any attribute are done through these indices.
• The guid field gives the global unique ID of the given attribute. You can also refer to any attribute through its guid.
• The flags field describes some attribute type dependent information. Possible values are listed at the same place where the given attribute structure is.
• The name field gives the name of the attribute which appears in the appropriate dialogs.
• The modiTime field tells you when the attribute was last modified.

Many attribute related functions use the API_Attribute structure on the parameter list. As a general rule, you have to fill the required fields in the union, then Archicad parses the request based on the values and passes the return parameters in the same parameter. This is why most of the functions do not have the const directive in the prototypes.

---

Retrieving an attribute

Let's see a simple example. Assume you are interested in the definition of the second line type of the data structure. In this case you should use a variable with the type API_Attribute structure.

API_Attribute    attrib = {};
GSErrCode        err;
 
attrib.header.typeID = API_LinetypeID;
attrib.header.index  = 2;
 
err = ACAPI_Attribute_Get (&attrib);

The description of the attribute is returned in the attrib.linetype part of the union. With this function call, you get the basic data of the given attribute, such as the name, the flags, the defined scale, etc., but you do not get the definition of the actual shape of the line type. Since producing this data may be a relatively a long conversion process, this information can be obtained with an additional function call.

API_AttributeDef    defs;
err = ACAPI_Attribute_GetDef (API_LinetypeID, 2, &defs);

In this case, you have all of the additional data related to the particular attribute. The API_AttributeDef structure is a collection of several handles (dynamic memory). If any of them are allocated it contains data. If you do not need the data any more, you have to free the allocated memory blocks to avoid memory leaks. The suggested way is the following:

ACAPI_DisposeAttrDefsHdls (&defs);

If you use this function, it is ensured that all of the dynamic data will be freed, and also that there will be no compatibility problems if your add-on is installed to a newer version of Archicad.

It is very important to examine the error codes returned by the API functions, and parse the returned value.

A typical situation is when you want to go through the instances of a particular attribute type in the database. The following example gives a good template to do that.

API_Attribute  attrib = {};
short      nLin, i;
GSErrCode  err;
 
attrib.header.typeID = API_LinetypeID;
err = ACAPI_Attribute_GetNum (API_LinetypeID, &nLin);
for (i = 1; i <= nLin && err == NoError; i++) {
    attrib.header.index = i;
    err = ACAPI_Attribute_Get (&attrib);
    if (err == NoError) {
        /* do what you want */
    }
    if (err == APIERR_DELETED)
        err = NoError;
}

First you need to get the number of line types in the database. You can do that with the ACAPI_Attribute_GetNum function, but be careful. This function returns the largest index used in the database, not the number of installed attributes, because instances may be deleted. Deleted attributes are not purged from the database immediately, which means that the valid index range is not (always) continuous. This is why the APIERR_DELETED return code has to be handled.

---

Creating an attribute

The attribute creation process is also fairly simple. All you have to do is to fill the appropriate part of the API_Attribute, and optionally the API_AttributeDefExt structure. The ACAPI_Attribute_CreateExt function does the following:

• It checks the data for possible inconsistency. If some problem is encountered it may be corrected automatically or an error code is generated.
• It ignores for example, the index field in the header structure, you cannot influence which index the attribute should be referenced by. This value is automatically generated and returned to you.
• If an attribute exists with the same name in the database, the existing index will be returned. The matching procedure ignores the differences of the attribute definition. Multiple attributes with the same name are not allowed.
• The generated attribute is placed in the data structure and it can be referenced in any subsequent API call.

It is very important that Archicad does not free any dynamic data structure you have allocated and passed to Archicad. They must be freed by your code.

Another important note is the following. Every data structure filled by you must be initialized to zero, for forward compatibility. Fillers may become real data fields in the later versions of the API, so if they are not initialized to zero, the result may be unpredictable.

The template to create an attribute is the following:

API_Attribute          attrib = {};
API_AttributeDefsExt   defs = {};
short               ltypeIndex;
GSErrCode           err;
 
attrib.header.typeID = API_LinetypeID;
/* fill attrib.linetype */
/* fill defs for dashed and symbol line types */
 
err = ACAPI_Attribute_CreateExt (&attrib, &defs);
ltypeIndex = attrib.header.index;
 
ACAPI_DisposeAttrDefsHdlsExt (&defs);

Handler Functions

All of the attribute handler functions begins with the ACAPI_Attribute_ prefix. This function family gives support to query the attribute database, to modify the existing items, and also to create new instances. Refer to the functions below to have details on these topics.

• ACAPI_Attribute_GetNum
• ACAPI_Attribute_Search
• ACAPI_Attribute_Get
• ACAPI_Attribute_GetDef
• ACAPI_Attribute_GetDefExt
• ACAPI_Attribute_Create
• ACAPI_Attribute_CreateExt
• ACAPI_Attribute_Delete
• ACAPI_Attribute_DeleteMore
• ACAPI_Attribute_Modify
• ACAPI_Attribute_ModifyExt

Controlling the user data assigned to an attribute:

• ACAPI_UserData_SetUserData
• ACAPI_UserData_GetUserData

Controlling the classifications and properties assigned to an attribute:

• ACAPI_Attribute_GetClassificationItems
• ACAPI_Attribute_GetClassificationInSystem
• ACAPI_Attribute_AddClassificationItem
• ACAPI_Attribute_RemoveClassificationItem
• ACAPI_Attribute_IsClassificationItemVisible
• ACAPI_Attribute_GetPropertyDefinitions
• ACAPI_Attribute_GetPropertyValue
• ACAPI_Attribute_GetPropertyValues
• ACAPI_Attribute_GetPropertyValuesByGuid
• ACAPI_Attribute_SetProperty
• ACAPI_Attribute_SetProperties
• ACAPI_Attribute_IsPropertyDefinitionValueEditable
• ACAPI_Attribute_IsPropertyDefinitionAvailable
• ACAPI_Attribute_IsPropertyDefinitionVisible
• ACAPI_Attribute_GetAttributesFromProject

Handling attribute folders:

• ACAPI_Attribute_GetFolder
• ACAPI_Attribute_CreateFolder
• ACAPI_Attribute_DeleteFolder
• ACAPI_Attribute_RenameFolder
• ACAPI_Attribute_GetFolderContent
• ACAPI_Attribute_Move

Controlling attribute user interface controls:

• ACAPI_Dialog_CreateAttributePicker
• ACAPI_Attribute_CreateAttributeFolderPicker

General Error Codes

APIERR_BADID

invalid reference;
the attribute type is invalid or the operation cannot apply that type

APIERR_BADINDEX

invalid reference;
the supplied attribute index is out of range

APIERR_DELETED

invalid reference;
the attribute does not exist in the database (deleted)

APIERR_NOTMINE

permission denied;
the attribute is out of the users workspace

Notes

There are certain rules which effect the attribute operations; i.e. they may be refused for some reason. The most important rules are:

• certain attribute types have a fixed number of instances (e.g. pens),
• certain attribute types must have at least one instance (e.g. line types),
• any type of modification is allowed only in the case when the target attribute instance is in the user's workspace

Typedef Documentation

API_AttributeReplaceIndexTable

API_AttributeReplaceIndexTable

Contains the deleted and replaced attribute indices grouped by attribute type.

Since

Archicad 25

APIAttributeReplacementHandlerProc

typedef GSErrCode __ACENV_CALL APIAttributeReplacementHandlerProc(const API_AttributeReplaceIndexTable &table)

User supplied callback procedure for handling attribute replacements.

Since

Archicad 25

Parameters

table

[in] List of attributes replaced. The hash key in the hash table is the type of attribute (material, profile etc.), the paired value is another hash table, which holds the old (deleted) attribute indices as keys, and the replacement attribute indices as values.

Returns

• NoError - The function has completed with success.

Remarks

This callback function should be implemented and set with ACAPI_Notification_CatchAttributeReplacement in order to receive notifications of attribute replacements.

Enumeration Type Documentation

API_LtypItemID

enum API_LtypItemID

Describes the various item types of a symbol line.

Remarks

These are the item types you can use to describe a symbol line.

Function Documentation

AC2API_AttrIndex()

API_AttributeIndex AC2API_AttrIndex ( const ADB::AttributeIndex &  acIndex )

inline

Converts an ADB::AttributeIndex to API_AttributeIndex.

Since

Archicad 27

Parameters

acIndex

[in]

Returns

• API_AttributeIndex

ACAPI_AddOnIntegration_InstallAttrManagerImportMethod()

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

Installs the import method for the Attribute Manager.

Since

Archicad 26

Parameters

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

Returns

• NoError - The function has completed with success.

Remarks

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

ACAPI_Attribute_AddClassificationItem()

GSErrCode __ACENV_CALL ACAPI_Attribute_AddClassificationItem	(	const API_Attr_Head &	attrHead,
		const API_Guid &	itemGuid
	)

Classifies an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
itemGuid	[in] The guid of the classification item, that should be added to the element.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_READONLY - The attribute can not be modified (i.e. from a hotlink) or you do not have the right to classify attributes in the current teamwork plan.
• APIERR_BADID - Inexistent classification item.
• APIERR_BADCLASSIFICATION - The classification item is not available for the given attribute.

ACAPI_Attribute_AddProperty()

GSErrCode __ACENV_CALL ACAPI_Attribute_AddProperty	(	API_PropertyDefinition &	definition,
		const GS::Array< API_Attr_Head > &	attrHeaders
	)

Makes a property definition available for all of given attributes (it is created if it does not exist).

Parameters

definition	[in/out] The GUID of the definition (if already existing) or the data of the definition to create. Once the operation is completed successfully this will hold the GUID of the definition (if newly created) and the modified availability array.
attrHeaders	[in] The array of attributes, that the property should be available for.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Do not have the right to create or modify a property definition on a teamwork server.
• APIERR_NAMEALREADYUSED - The name of the definition is already used in the given property group.
• APIERR_READONLY - Tried to modify a read-only property (for example a property coming from a hotlink).
• APIERR_BADPARS - The value of the definition is inconsistent, for example the default value has a different value type than the definition itself.
• APIERR_BADVALUE - One of enumerations did not have their value out of the allowed ones. This includes c++ enums (i.e. they were uninitialized or memsetted), and enumeration property values (the possibleEnumValues doesn't contain the default value)

Example

GSErrCode CreateExamplePropertyDefinitionForSelection (API_Guid groupGuid, const GS::Array<API_Attr_Head>& attributes, API_PropertyDefinition& definition)
{
    definition.guid = APINULLGuid;
    definition.groupGuid = groupGuid;
    definition.name = "Property Definition";
    definition.description = "An example property definition.";
    definition.collectionType = API_PropertySingleCollectionType;
    definition.valueType = API_PropertyBooleanValueType;
    definition.defaultValue.singleVariant.variant.type = definition.valueType;
    definition.defaultValue.singleVariant.variant.boolValue = false;
 
    return ACAPI_Attribute_AddProperty (definition, attributes);
}

ACAPI_Attribute_Create()

GSErrCode __ACENV_CALL ACAPI_Attribute_Create	(	API_Attribute *	attribute,
		API_AttributeDef *	defs
	)

Creates an attribute.

Since

Archicad 26

Parameters

attribute	[in/out] Parameters of the attribute. The type of the attribute must be passed in the typeID field in the attribute header. The index field of the attribute header is used as an output parameter to return the reference index to the newly created attribute.
defs	[in] Additional parameters of the attribute. It is required or optional to pass depending on the type of the attribute.

Returns

• NoError - The function has completed with success.
• APIERR_ATTREXIST - An attribute with the same name already exists.
• APIERR_BADID - Invalid attribute type was passed, or a pen or font attribute type was given.
• APIERR_BADPARS - A nullptr attribute pointer was passed.
• APIERR_NOTMINE - You are in view-only mode for a teamwork project.

Remarks

This function is used to create an attribute, defined by the typeID field of the attribute header. The reference index of the newly created attribute is returned in the index field of the attribute header. You cannot create pen and font attributes. The function also checks the data for possible inconsistency. If a problem is encountered it may be corrected automatically, or an error code is generated. If an attribute with the same name exists in the database, the existing index will be returned. The matching procedure ignores the differences of the attribute definition. Multiple attributes with the same name are not allowed. When creating the attribute, the applicable fields should be filled. API_Attr_Head typeID required index ignored flags required where applicable name required API_AttributeTypeID defs API_LayerID - API_LinetypeID ltype_dashItems (for dashed line type) ltype_lineItems(for symbol line type) API_FilltypeID fill_lineItems (for vector fill type) fill_lineLength (for vector fill type) sfill_Items (for symbol fill type) API_CompWallID cwall_compItems API_MaterialID - API_LayerCombID layer_statItems API_ZoneCatID zone_addParItems API_MEPSystemID - It is important that Archicad does not free any dynamic data structure you have allocated and passed to Archicad. It is your responsibility to dispose the handles passed in the defs parameter, when they are no longer needed. It is advised to use the ACAPI_DisposeAttrDefsHdls function for compatibility reasons. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview. You cannot create pen and font attributes. The function also checks the data for possible inconsistency. If a problem is encountered it may be corrected automatically, or an error code is generated. If an attribute with the same name exists in the database, the existing index will be returned. The matching procedure ignores the differences of the attribute definition. Multiple attributes with the same name are not allowed. When creating the attribute, the applicable fields should be filled. Use this function instead of ACAPI_Attribute_Create function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef.

API_Attr_Head
typeID	required
index	ignored
flags	required where applicable
name	required

API_AttributeTypeID	defs
API_LayerID	-
API_LinetypeID	ltype_dashItems (for dashed line type)

ltype_lineItems(for symbol line type)| |API_FilltypeID|fill_lineItems (for vector fill type) fill_lineLength (for vector fill type) sfill_Items (for symbol fill type)| |API_CompWallID|cwall_compItems| |API_MaterialID|-| |API_LayerCombID|layer_statItems| |API_ZoneCatID|zone_addParItems| |API_MEPSystemID|-|

It is important that Archicad does not free any dynamic data structure you have allocated and passed to Archicad. It is your responsibility to dispose of the handles passed in the defs parameter, when they are no longer needed. It is advised to use the ACAPI_DisposeAttrDefsHdlsExt function for compatibility reasons. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Attribute      attrib;
API_AttributeDefs  defs;
short              ltypeIndex;
GSErrCode          err;
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
BNZeroMemory (&defs, sizeof (API_AttributeDefs));
 
attrib.header.typeID = API_LinetypeID;
/* fill attrib.linetype */
/* fill defs for non solid linetypes */
 
err = ACAPI_Attribute_Create (&attrib, &defs);
ltypeIndex = attrib.header.index;
 
ACAPI_DisposeAttrDefsHdls (&defs);

ACAPI_Attribute_CreateAttributeFolderPicker()

GSErrCode __ACENV_CALL ACAPI_Attribute_CreateAttributeFolderPicker	(	const API_AttributeFolderPickerParams &	attributeFolderPickerParams,
		GS::Owner< API_AttributeFolderPicker > &	attributeFolderPicker
	)

Enables the attribute folder picker functionality for a push check, if the user clicks the push check, the picker will open. Attributes folder pickers can be used to choose an attribute folder.

Since

Archicad 26

Parameters

attributeFolderPickerParams	[in] Parameters of attribute folder picker (type of the attribute, the parameters of push check).
attributeFolderPicker	[out] The constructed picker.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect attributeFolderPickerParams was specified.

ACAPI_Attribute_CreateExt()

GSErrCode __ACENV_CALL ACAPI_Attribute_CreateExt	(	API_Attribute *	attribute,
		API_AttributeDefExt *	defs
	)

Creates an attribute.

Since

Archicad 26

Parameters

attribute	[in/out] Parameters of the attribute. The type of the attribute must be passed in the typeID field in the attribute header. The index field of the attribute header is used as an output parameter to return the reference index to the newly created attribute.
defs	[in] Additional parameters of the attribute. It is required or optional to pass depending on the type of the attribute.

Returns

• NoError - The function has completed with success.
• APIERR_ATTREXIST - An attribute with the same name already exists.
• APIERR_BADID - Invalid attribute type was passed, or a pen or font attribute type was given.
• APIERR_BADPARS - A nullptr attribute pointer was passed.
• APIERR_NOTMINE - You are in view-only mode for a teamwork project.

Remarks

This function is used to create an attribute, defined by the typeID field of the attribute header. The reference index of the newly created attribute is returned in the index field of the attribute header. You cannot create pen and font attributes. The function also checks the data for possible inconsistency. If a problem is encountered it may be corrected automatically, or an error code is generated. If an attribute with the same name exists in the database, the existing index will be returned. The matching procedure ignores the differences of the attribute definition. Multiple attributes with the same name are not allowed. When creating the attribute, the applicable fields should be filled. API_Attr_Head typeID required index ignored flags required where applicable name required API_AttributeTypeID defs API_LayerID - API_LinetypeID ltype_dashItems (for dashed line type) ltype_lineItems(for symbol line type) API_FilltypeID fill_lineItems (for vector fill type) fill_lineLength (for vector fill type) sfill_Items (for symbol fill type) API_CompWallID cwall_compItems API_MaterialID - API_LayerCombID layer_statItems API_ZoneCatID zone_addParItems API_MEPSystemID - It is important that Archicad does not free any dynamic data structure you have allocated and passed to Archicad. It is your responsibility to dispose the handles passed in the defs parameter, when they are no longer needed. It is advised to use the ACAPI_DisposeAttrDefsHdls function for compatibility reasons. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview. You cannot create pen and font attributes. The function also checks the data for possible inconsistency. If a problem is encountered it may be corrected automatically, or an error code is generated. If an attribute with the same name exists in the database, the existing index will be returned. The matching procedure ignores the differences of the attribute definition. Multiple attributes with the same name are not allowed. When creating the attribute, the applicable fields should be filled. Use this function instead of ACAPI_Attribute_Create function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef.

API_Attr_Head
typeID	required
index	ignored
flags	required where applicable
name	required

API_AttributeTypeID	defs
API_LayerID	-
API_LinetypeID	ltype_dashItems (for dashed line type)

ltype_lineItems(for symbol line type)| |API_FilltypeID|fill_lineItems (for vector fill type) fill_lineLength (for vector fill type) sfill_Items (for symbol fill type)| |API_CompWallID|cwall_compItems cwall_compLItems| |API_MaterialID|-| |API_LayerCombID|layer_statItems| |API_ZoneCatID|zone_addParItems| |API_MEPSystemID|-|

It is important that Archicad does not free any dynamic data structure you have allocated and passed to Archicad. It is your responsibility to dispose the handles passed in the defs parameter, when they are no longer needed. It is advised to use the ACAPI_DisposeAttrDefsHdlsExt function for compatibility reasons. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Attribute         attrib;
API_AttributeDefsExt  defs;
short                 ltypeIndex;
GSErrCode             err;
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
BNZeroMemory (&defs, sizeof (API_AttributeDefsExt));
 
attrib.header.typeID = API_LinetypeID;
/* fill attrib.linetype */
/* fill defs for non solid linetypes */
 
err = ACAPI_Attribute_CreateExt (&attrib, &defs);
ltypeIndex = attrib.header.index;
 
ACAPI_DisposeAttrDefsHdlsExt (&defs);

ACAPI_Attribute_CreateFolder()

GSErrCode __ACENV_CALL ACAPI_Attribute_CreateFolder

(

API_AttributeFolder &

folder

)

Creates attribute folders. To create a folder, its full path has to be provided. The command will create all folders along the path, if they do not exist.

Since

Archicad 26

Parameters

folder

[in out] Type and path of the attribute folder to create.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect folder.typeID was specified, or folder.path is illegal, see remarks.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOACCESSRIGHT - User has no permission to create folders under typeID.
• APIERR_BADPARS - Folder creation is not available for folder.typeID.

Remarks

older.path has to be legal, i.e. all names in the array must not be empty, and must not begin or end with whitespace. If a folder in folder.path already exists, it is not renamed or recreated. Name collision of folders is case insensitive. Examples:

• If the folders A/B exist, and folder.path = a/b/c/d, two new folders, c/d under A/B are created. A and B are not renamed to a and b.
• If the folders A/B/C exist, and folder.path = a/b/c, this has no effect. NoError will be returned. If a folder at folder.path was successfully created, it's unique identifier is set to folder.guid. It can be used later, even if the folder was moved or renamed since it's creation.

Example

    API_AttributeFolder folder {};
    folder.typeID = API_CompWallID;
    folder.path = { "A", "B", "C1" };
    DBVERIFY (ACAPI_Attribute_CreateFolder (folder) == NoError);

ACAPI_Attribute_Delete()

GSErrCode __ACENV_CALL ACAPI_Attribute_Delete

(

const API_Attr_Head &

attrHead

)

Deletes an attribute.

Since

Archicad 26

Parameters

attrHead

[in] The typeID and index fields in the header identifies the attribute to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter (attrHead) is invalid.
• APIERR_REFUSEDPAR - You tried to delete pens, fonts, a solid or an empty fill, or an attribute with index 1.
• APIERR_NOTMINE - The attribute is out of the users workspace.

Remarks

This function is used to delete an attribute, defined by the typeID and index field of the attribute header. Certain attributes in the database can not be deleted; see the return values. Note, that deleting an attribute do not effect any changes in the element database; they will refer to an attribute which is missing. That is not a problem, the server applications work in the same way when an attribute is deleted from the menus. The only exception is the layer attribute. Once a layer is deleted all the elements will be deleted; no matter in which database they are. The floor plan and all the section/elevations will be scanned to delete the elements which are on the given layer. You can delete more than one attribute of the same type with the ACAPI_Attribute_DeleteMore function. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Attribute attrib = {};
attrib.header.typeID = API_LinetypeID;
attrib.header.index = 5;
 
GSErrCode err = ACAPI_Attribute_Delete (attrib.header);

ACAPI_Attribute_DeleteFolder()

GSErrCode __ACENV_CALL ACAPI_Attribute_DeleteFolder

(

const API_AttributeFolder &

folder

)

Deletes an attribute folder and all the folders and attributes it contains.

Since

Archicad 26

Parameters

folder

[in] The folder to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect folder was specified.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOACCESSRIGHT - User has no permission to delete folders under folder.typeID.
• APIERR_NOTMINE - Attribute type folder.typeID is not reserved.

Remarks

Folder has to be an existing folder identified by it's typeID, and path or guid.. Deletes all deletable attributes and folders the given folder contains. If an attribute is not deletable, the folders containing the attribute are not deleted. newName has to be legal, must not be empty, and must not begin or end with whitespace. Renames the specified folder (while preserving it's guid). The root folder can't be renamed, two folders in the same parent folder can't have the same name.

Example

API_AttributeFolder lineFolder {};
lineFolder.typeID = API_LinetypeID;
lineFolder.path = { "A", "B", "C" };
ACAPI_Attribute_DeleteFolder (lineFolder);
 
API_AttributeFolder cwFolder {};
cwFolder.typeID = API_CompWallID;
cwFolder.guid = GS::Guid ("27075EFF-611F-4B11-9BBB-553AC8BDA922");
ACAPI_Attribute_DeleteFolder (cwFolder);

ACAPI_Attribute_DeleteMore()

GSErrCode __ACENV_CALL ACAPI_Attribute_DeleteMore	(	API_AttrTypeID	attrTypeID,
		const GS::Array< API_AttributeIndex > &	attrIndexList
	)

Deletes more attributes of the same type.

Since

Archicad 26

Parameters

attrTypeID	[in] Identifies the type of the attributes to delete.
attrIndexList	[in] List of attribute indices to be deleted.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter attrTypeID is invalid or the given attrIndexList is empty.
• APIERR_REFUSEDPAR - You tried to delete pens, fonts, a solid or an empty fill, or an attribute with index 1.
• APIERR_NOTMINE - The attribute is out of the users workspace.

Remarks

This function is the extension of ACAPI_Attribute_Delete. You can specify a list of attribute indices to be deleted. If you pass only one index in the attrIndexList parameter, this function works like ACAPI_Attribute_Delete. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GSErrCode err = ACAPI_Attribute_DeleteMore (API_LinetypeID, { 3, 4, 5 });
if (err != NoError) {
    // failed to delete the attributes
}

ACAPI_Attribute_DeleteProperty()

GSErrCode __ACENV_CALL ACAPI_Attribute_DeleteProperty	(	const API_Guid &	definitionGuid,
		const GS::Array< API_Attr_Head > &	attrHeaders
	)

Makes a property definition unavailable for all of given attributes.

Parameters

definitionGuid	[in] The GUID of the definition to remove from the attributes.
attrHeaders	[in] The array of attributes, that the property should be available for.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Do not have the right to modify a property definition on a teamwork server.
• APIERR_BADID - Inexistent property item.
• APIERR_READONLY - Tried to modify a read-only property (for example a property coming from a hotlink).

Example

GSErrCode DeleteIntegerPropetiesOfSelection (GS::Array<API_Attr_Head>& attributes)
{
    GS::Array<API_PropertyDefinition> definitions;
    ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
 
    for (UIndex i = 0; i < definitions.GetSize (); ++i) {
        if (definitions[i].collectionType == API_PropertySingleCollectionType &&
            definitions[i].valueType == API_PropertyIntegerValueType) {
            GSErrCode err = ACAPI_Attribute_DeleteProperty (definitions[i].guid, attributes));
            if (err != NoError) {
                return err;
            }
        }
    }
    return NoError;
}

ACAPI_Attribute_EnumerateAttributesByType()

GSErrCode __ACENV_CALL ACAPI_Attribute_EnumerateAttributesByType	(	API_AttrTypeID	typeID,
		const std::function< void(API_Attribute &)> &	processor
	)

Iterates the instances of a given attribute type in the database.

Since

October 18, 2022

Parameters

typeID	[in] Type of the attribute.
processor	[in] The enumerator process on the API_Attribute as a lambda function.

Returns

ACAPI_Attribute_Get()

GSErrCode __ACENV_CALL ACAPI_Attribute_Get

(

API_Attribute *

attribute

)

Retrieves an attribute from the database.

Since

Archicad 27

Parameters

attribute

[in/out] Parameters of the attribute. The type and the index or the name of the attribute must be passed in the typeID and index, or in the typeID and name fields in the attribute header. The data of the attribute is returned in the appropriate fields of the API_Attribute structure.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter (attribute) is nullptr
• APIERR_BADID - The attribute type is invalid
• APIERR_BADINDEX - The attribute index is invalid; if referenced by index
• APIERR_BADNAME - The attribute with the given name doesn't exist; if referenced by name

Remarks

This function is used to retrieve one attribute's data from the database. Beside the typeID, you should specify either the index or the name field of the header. In the latter case, the index field should be set to zero, and the attribute database is searched by name. You may optionally call ACAPI_Attribute_GetDef to get extended information for certain attribute types. The index range is not always continuous; deleted attributes are not purged immediately from the database. Note: The received attributes can have dynamically allocated members depending on the typeID. They should be disposed when they are no more needed.

• API_MaterialID : attribute.material.texture.fileLoc
• API_ModelViewOptionsID : attribute.modelViewOpt.modelViewOpt.gdlOptions Note: Special pen IDs can be used:
• 1000 : returns the color of the grid line
• 1001 : returns the color of the zone stamp
• 1002 : returns the color of the ghost story

Example

/* Example I -- get an attribute */
API_Attribute     attrib;
GSErrCode         err;
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
 
/* get the "Wave" line type */
attrib.header.typeID = API_LinetypeID;
CHCopyC ("Wave", attrib.header.name);
 
err = ACAPI_Attribute_Get (&attrib);
 
 
 
/* Example II -- loop through all attributes of a kind */
API_Attribute  attrib;
short          nLin, i;
GSErrCode      err;
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
attrib.header.typeID = API_LinetypeID;
err = ACAPI_Attribute_GetNum (API_LinetypeID, &nLin);
for (i = 1; i <= nLin && err == NoError; i++) {
    attrib.header.index = i;
    err = ACAPI_Attribute_Get (&attrib);
    if (err == NoError) {
        /* do what you want */
    }
    if (err == APIERR_BADINDEX)
        err = NoError;
}

ACAPI_Attribute_GetAttributesByType()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetAttributesByType	(	API_AttrTypeID	typeID,
		GS::Array< API_Attribute > &	attributes
	)

Returns the instances of a given attribute type in the database.

Since

Archicad 27

Parameters

typeID	[in] Type of the attribute.
attributes	[out] The attributes in the database for the given attribute type.

Returns

ACAPI_Attribute_GetAttributesFromProject()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetAttributesFromProject	(	const IO::Location &	location,
		API_AttrTypeID	typeID,
		GS::Array< GS::Pair< API_Attribute, API_AttributeDefExt > > *	resultArray
	)

Loads the given attributes from a project file.

Parameters

location	[in] The location of the project to load the attributes from.
typeID	[in] The attribute type to load from the project.
resultArray	[out] The list of attributes that has been loaded successfully.

Returns

• NoError - The function has completed with success.

Remarks

Be aware that certain attribute types (e.g., composite walls) refer to other attribute types as well.

ACAPI_Attribute_GetClassificationInSystem()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetClassificationInSystem	(	const API_Attr_Head &	attrHead,
		const API_Guid &	systemGuid,
		API_ClassificationItem &	item
	)

Retrieves a classification of an attribute in a given classification system.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
systemGuid	[in] The guid of the classification system in which the classification item should be retrieved.
item	[out] The retrieved classification item (empty with null guid if the elem doesn't have a classification in the given system).

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_BADID - Inexistent classification system.

ACAPI_Attribute_GetClassificationItems()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetClassificationItems	(	const API_Attr_Head &	attrHead,
		GS::Array< GS::Pair< API_Guid, API_Guid > > &	systemItemPairs
	)

Retrieves all of the classifications of an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
systemItemPairs	[out] A list of classification system and classification item guid pairs, that represent the attribute's classifications.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_GENERAL - Internal error.

ACAPI_Attribute_GetCurrentAttributeSetReader()

Modeler::IAttributeReader *__ACENV_CALL ACAPI_Attribute_GetCurrentAttributeSetReader

(

)

Returns an attribute reader for the currently used attribute set.

Since

Archicad 25

Returns

Remarks

Use this function when an attribute reader is required as a parameter of other functions. For example when retrieving the 3D model by using the EXPGetModel function. The returned attribute reader is allocated on the heap. Don't forget to delete it when it's not needed anymore!

ACAPI_Attribute_GetCurrPenSet()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetCurrPenSet

(

API_AttributeIndex *

penSetIndex

)

Get current pen set index.

Parameters

penSetIndex

[out] Current pen set index.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect penSetIndex was specified.

ACAPI_Attribute_GetDef()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetDef	(	API_AttrTypeID	typeID,
		API_AttributeIndex	index,
		API_AttributeDef *	defs
	)

Retrieves extended information for an attribute.

Since

Archicad 27

Parameters

typeID	[in] Type of the attribute.
index	[in] Index of the attribute.
defs	[out] The extended information for an attribute.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter (defs) is nullptr
• APIERR_BADID - The attribute type is invalid; see Remarks
• APIERR_BADINDEX - The attribute index is invalid

Remarks

This function is used to return detailed information on the specified attribute. This function is available only for lines, fills, composites, layers, and zone categories. Other type of attributes do not have extended information; all of the their data can be passed through the API_Attribute structure. See the ACAPI_Attribute_Get function to get the base parameters of an attribute. Do not forget to dispose the returned data handles if they are not needed any more. Use the ACAPI_DisposeAttrDefsHdls function for this purpose. This function is available only for lines, fills, composites, layers, and zone categories. Other type of attributes do not have extended information; all of the their data can be passed through the API_Attribute structure. See the ACAPI_Attribute_Get function to get the base parameters of an attribute. Do not forget to dispose the returned data handles if they are not needed any more. Use the ACAPI_DisposeAttrDefsHdlsExt function for this purpose. Use this function instead of ACAPI_Attribute_GetDef function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef.

Example

API_Attribute        attrib;
API_AttributeDefs    defs;
GSErrCode            err;
 
/* retrieve all information for the "Wave" linetype */
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
BNZeroMemory (&defs, sizeof (API_AttributeDefs));
 
attrib.header.typeID = API_LinetypeID;
CHCopyC ("Wave", attrib.header.name);
err = ACAPI_Attribute_Get (&attrib);
if (err == NoError)
    err = ACAPI_Attribute_GetDef (attrib.header.typeID, attrib.header.index, &defs);
ACAPI_DisposeAttrDefsHdls (&defs);

ACAPI_Attribute_GetDefExt()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetDefExt	(	API_AttrTypeID	typeID,
		API_AttributeIndex	index,
		API_AttributeDefExt *	defs
	)

Retrieves extended information for an attribute.

Since

Archicad 27

Parameters

typeID	[in] Type of the attribute.
index	[in] Index of the attribute.
defs	[out] The extended information for an attribute.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter (defs) is nullptr
• APIERR_BADID - The attribute type is invalid; see Remarks
• APIERR_BADINDEX - The attribute index is invalid

Remarks

This function is used to return detailed information on the specified attribute. This function is available only for lines, fills, composites, layers, and zone categories. Other type of attributes do not have extended information; all of the their data can be passed through the API_Attribute structure. See the ACAPI_Attribute_Get function to get the base parameters of an attribute. Do not forget to dispose the returned data handles if they are not needed any more. Use the ACAPI_DisposeAttrDefsHdls function for this purpose. This function is available only for lines, fills, composites, layers, and zone categories. Other type of attributes do not have extended information; all of the their data can be passed through the API_Attribute structure. See the ACAPI_Attribute_Get function to get the base parameters of an attribute. Do not forget to dispose the returned data handles if they are not needed any more. Use the ACAPI_DisposeAttrDefsHdlsExt function for this purpose. Use this function instead of ACAPI_Attribute_GetDef function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef.

Example

API_Attribute          attrib;
API_AttributeDefsExt   defs;
GSErrCode              err;
 
/* retrieve all information for the "Comp Wall 0.6" composite */
 
BNZeroMemory (&attrib, sizeof (API_Attribute));
BNZeroMemory (&defs, sizeof (API_AttributeDefsExt));
 
attrib.header.typeID = API_CompWallID;
CHCopyC ("Comp Wall 0.6", attrib.header.name);
err = ACAPI_Attribute_Get (&attrib);
if (err == NoError)
    err = ACAPI_Attribute_GetDefExt (attrib.header.typeID, attrib.header.index, &defs);
ACAPI_DisposeAttrDefsHdlsExt (&defs);

ACAPI_Attribute_GetFirstValidAttribute()

API_AttributeIndex __ACENV_CALL ACAPI_Attribute_GetFirstValidAttribute

(

API_AttrTypeID

typeID

)

Returns the first valid attribute index.

Parameters

typeID

type of Attribute

Since

Archicad 27

Returns

• API_AttributeIndex - the index of the first valid attribute of type or APIInvalidAttributeIndex

ACAPI_Attribute_GetFolder()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetFolder

(

API_AttributeFolder &

folder

)

Retrieves an existing attribute folder by it's path or guid.

Since

Archicad 26

Parameters

folder

[in out] Set the typeID and the path or guid of the attribute folder to retrieve.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect folder.typeID was specified, or folder.path is illegal, see remarks.
• APIERR_NOPLAN - There is no open project.

Remarks

folder.path has to be legal, i.e. all names in the array must not be empty, and must not begin or end with whitespace. Besides folder.typeID, either folder.guid or folder.path is to be passed. If none of the latter is provided, the root folder is accessed.

Example

    API_AttributeFolder folder {};
    folder.typeID = API_LinetypeID;
    folder.guid = GS::Guid ("27075EFF-611F-4B11-9BBB-553AC8BDA922");
    DBVERIFY (ACAPI_Attribute_GetFolder (folder) == NoError);
    for (const auto& name : folder.path) {
        // ...
    }

ACAPI_Attribute_GetFolderContent()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetFolderContent	(	const API_AttributeFolder &	folder,
		API_AttributeFolderContent &	result
	)

Returns all folders and attributes of an attribute type.

Since

Archicad 26

Parameters

folder	[in] Identifier of the folder to query.
result	[out] Content of te queried folder.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect folder was specified.
• APIERR_NOPLAN - There is no open project.

ACAPI_Attribute_GetNum()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetNum	(	API_AttrTypeID	typeID,
		UInt32 &	count
	)

Returns the number of instances of a given type of attribute.

Parameters

typeID	[in] Type of the attribute.
count	[out] The number of attributes in the database for the given attribute type.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; count
• APIERR_BADID - The attribute type is invalid

Remarks

This function returns the actual number of the given attribute type. You should use ACAPI_Attribute_GetAttributesByType or ACAPI_Attribute_EnumerateAttributesByType to iterate on attributes!.

Example

API_AttributeIndex  ltypeNum;
GSErrCode           err;
 
/* find out how many linetypes we have */
 
err = ACAPI_Attribute_GetNum (API_LinetypeID, &ltypeNum);

ACAPI_Attribute_GetPen()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPen

(

API_Pen &

pen

)

Returns a pen by index from the active pentable.

Since

Archicad 27

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - bad pen index
• APIERR_NOCURRATTRSET - no current attributeset

ACAPI_Attribute_GetPenNum()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPenNum

(

UInt32 &

count

)

Get the number of pens in the active pentable.

Since

Archicad 27

Returns

• NoError - The function has completed with success.
• APIERR_NOCURRATTRSET - no current attributeSet exists

ACAPI_Attribute_GetPropertyDefinitions()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPropertyDefinitions	(	const API_Attr_Head &	attrHead,
		API_PropertyDefinitionFilter	filter,
		GS::Array< API_PropertyDefinition > &	definitions
	)

Retrieves all of the built-in property definitions that are available for an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
filter	[in] Get the definition for user defined, fundamental or user-level built-in attributes.
definitions	[out] Array of property definitions that are available for a classification of the given attribute.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.

Example

GSErrCode GetPropertyDefinitionNames (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<GS::UniString>& names)
{
    API_Attr_Head                     attributeHeader = {};
    GS::Array<API_PropertyDefinition> definitions;
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index  = attributeIndex;
 
    GSErrCode error = ACAPI_Attribute_GetPropertyDefinitions (attributeHeader, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            names.Push(definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Attribute_GetPropertyValue()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPropertyValue	(	const API_Attr_Head &	attrHead,
		const API_Guid &	propertyDefinitionGuid,
		API_Property &	property
	)

Retrieves the property value of the property definition.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyDefinitionGuid	[in] Property definition.
property	[out] Property value.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_GENERAL - Every other case.

Example

GSErrCode GetPropertyDefinitionNames (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<GS::UniString>& names)
{
    API_Attr_Head                     attributeHeader = {};
    GS::Array<API_PropertyDefinition> definitions;
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Attribute_GetPropertyDefinitions (attributeHeader, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            API_Property property = {};
 
            error = ACAPI_Attribute_GetPropertyValue (attributeHeader, definitions [i], property);
        }
    }
 
    return error;
}

ACAPI_Attribute_GetPropertyValues()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPropertyValues	(	const API_Attr_Head &	attrHead,
		const GS::Array< API_PropertyDefinition > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the property values of the property definitions.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyDefinitions	[in] List of property definitions.
properties	[out] List of property values.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_GENERAL - Every other case.

Example

GSErrCode GetPropertyDefinitionNames (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<GS::UniString>& names)
{
    API_Attr_Head                     attributeHeader = {};
    GS::Array<API_PropertyDefinition> definitions;
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Attribute_GetPropertyDefinitions (attributeHeader, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Attribute_GetPropertyValues (attributeHeader, definitions, properties);
        }
    }
 
    return error;
}

ACAPI_Attribute_GetPropertyValuesByGuid()

GSErrCode __ACENV_CALL ACAPI_Attribute_GetPropertyValuesByGuid	(	const API_Attr_Head &	attrHead,
		const GS::Array< API_Guid > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the property values of the property definitions.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyDefinitions	[in] List of property definitions identified by guid.
properties	[out] List of property values.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_GENERAL - Every other case.

ACAPI_Attribute_IsClassificationItemVisible()

bool __ACENV_CALL ACAPI_Attribute_IsClassificationItemVisible	(	const API_Attr_Head &	attrHead,
		const API_Guid &	classificationGuid
	)

Tells whether a classification item is visible for an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
classificationGuid	[in] The classification item GUID to search for.

Returns

• true - The given classification item is visible for the attribute. It can return true even if the parent of the classification item is hidden.
• false - The given classification item is not visible for the attribute or invalid parameters.

Example

GSErrCode GetVisibleClassificationItems (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<API_ClassificationItem>& visibleClassifications)
{
    API_Attr_Head                     attributeHeader = {};
    GS::Array<API_ClassificationItem> definitions;
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Classification_GetClassificationItems (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Attribute_IsClassificationItemVisible (attributeHeader, definitions[i].guid)) {
                visibleClassifications.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Attribute_IsPropertyDefinitionAvailable()

bool __ACENV_CALL ACAPI_Attribute_IsPropertyDefinitionAvailable	(	const API_Attr_Head &	attrHead,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is available for an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is available for the attribute.
• false - The given property definition is not available for the attribute or invalid parameters.

Example

GSErrCode GetAvailablePropertyDefinitions (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<API_PropertyDefinition>& availableProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    API_Attr_Head                     attributeHeader = {};
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Attribute_IsPropertyDefinitionAvailable (attributeHeader, definitions[i].guid)) {
                availableProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Attribute_IsPropertyDefinitionValueEditable()

bool __ACENV_CALL ACAPI_Attribute_IsPropertyDefinitionValueEditable	(	const API_Attr_Head &	attrHead,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is editable for an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is editable for the attribute.
• false - The given property definition is not editable for the attribute or invalid parameters.

Example

GSErrCode GetAvailablePropertyDefinitions (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<API_PropertyDefinition>& availableProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    API_Attr_Head                     attributeHeader = {};
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Attribute_IsPropertyDefinitionAvailable (attributeHeader, definitions[i].guid)) {
                availableProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Attribute_IsPropertyDefinitionVisible()

bool __ACENV_CALL ACAPI_Attribute_IsPropertyDefinitionVisible	(	const API_Attr_Head &	attrHead,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is visible for an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is visible for the attribute.
• false - The given property definition is not visible for the attribute or invalid parameters.

Example

GSErrCode GetVisiblePropertyDefinitions (API_AttrTypeID attributeTypeID, short attributeIndex, GS::Array<API_PropertyDefinition>& visibleProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    API_Attr_Head                     attributeHeader = {};
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Attribute_IsPropertyDefinitionVisible (attributeHeader, definitions[i].guid)) {
                visibleProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Attribute_Modify()

GSErrCode __ACENV_CALL ACAPI_Attribute_Modify	(	API_Attribute *	attribute,
		API_AttributeDef *	defs
	)

Modifies an attribute.

Since

Archicad 27

Parameters

attribute	[in] The attribute to be modified is defined by the typeID and index fields of the header.
defs	[in] The extended information for the attribute where needed.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; attribute, [defs]
• APIERR_BADID - The attribute type is invalid
• APIERR_BADINDEX - The attribute index is invalid
• APIERR_REFUSEDPAR - For layers, fills and line types you cannot modify the attribute with index 1. Solid and empty fills are also unalterable.

Remarks

This function is used to modify an attribute. The attribute to be modified is identified by the typeID and the index fields in the attribute header. You can either modify the parameters passed through the API_Attribute structure or the extended information given in API_AttributeDef. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview. You can either modify the parameters passed through the API_Attribute structure or the extended information given in API_AttributeDefExt. Use this function instead of ACAPI_Attribute_Modify function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Attribute          attrib;
API_AttributeDefs      defs;
short                  ltypeIndex;
GSErrCode              err;
 
BNClear (attrib);
BNClear (defs);
 
/* retrieve all information for the "Wave" line type */
attrib.header.typeID = API_LinetypeID;
CHCopyC ("Wave", attrib.header.name);
err = ACAPI_Attribute_Get (&attrib);
if (err == NoError) {
    err = ACAPI_Attribute_GetDef (attrib.header.typeID, attrib.header.index, &defs);
}
 
if (err == NoError) {
    attrib.header.flags |= APILine_ScaleWithPlan;
    attrib.lineType.defineScale = 100.0;
    err = ACAPI_Attribute_Modify (&attrib, &defs);
}
 
ACAPI_DisposeAttrDefsHdls (&defs);

ACAPI_Attribute_ModifyExt()

GSErrCode __ACENV_CALL ACAPI_Attribute_ModifyExt	(	API_Attribute *	attribute,
		API_AttributeDefExt *	defs
	)

Modifies an attribute.

Since

Archicad 27

Parameters

attribute	[in] The attribute to be modified is defined by the typeID and index fields of the header.
defs	[in] The extended information for the attribute where needed.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; attribute, [defs]
• APIERR_BADID - The attribute type is invalid
• APIERR_BADINDEX - The attribute index is invalid
• APIERR_REFUSEDPAR - For layers, fills and line types you cannot modify the attribute with index 1. Solid and empty fills are also unalterable.

Remarks

This function is used to modify an attribute. The attribute to be modified is identified by the typeID and the index fields in the attribute header. You can either modify the parameters passed through the API_Attribute structure or the extended information given in API_AttributeDef. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview. You can either modify the parameters passed through the API_Attribute structure or the extended information given in API_AttributeDefExt. Use this function instead of ACAPI_Attribute_Modify function because API_AttributeDefExt structure contains more fields - detailed information for composite wall attribute - than API_AttributeDef. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Attribute           attrib;
API_AttributeDefsExt    defs;
short                   ltypeIndex;
GSErrCode               err;
 
BNClear (attrib);
BNClear (defs);
 
/* retrieve all information for the "Comp Wall 0.6" composite */
attrib.header.typeID = API_CompWallID;
CHCopyC ("Comp Wall 0.6", attrib.header.name);
err = ACAPI_Attribute_Get (&attrib);
if (err == NoError) {
    err = ACAPI_Attribute_GetDefExt (attrib.header.typeID, attrib.header.index, &defs);
}
 
if (err == NoError) {
    for (short i = 0; i < attrib.compWall.nComps + 1; i++) {
        (*defs.cwall_compLItems)[i].ltypeInd = 3;
        (*defs.cwall_compLItems)[i].linePen  = 3;
    }
    err = ACAPI_Attribute_ModifyExt (&attrib, &defs);
}
 
ACAPI_DisposeAttrDefsHdlsExt (&defs);

ACAPI_Attribute_ModifyPen()

GSErrCode __ACENV_CALL ACAPI_Attribute_ModifyPen

(

const API_Pen &

pen

)

Modify a pen by index in the active pentable.

Since

Archicad 27

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - no access right in teamwork
• APIERR_NOTMINE - pen tables not reserved in teamwork
• APIERR_General - general error
• APIERR_BADINDEX - bad pen index
• APIERR_NOCURRATTRSET - no current attributeset

ACAPI_Attribute_ModifyPropertyValue()

GSErrCode __ACENV_CALL ACAPI_Attribute_ModifyPropertyValue	(	const API_Property &	property,
		const GS::Array< API_Attr_Head > &	attrHeaders
	)

Sets the value of a property for multiple attributes. If the property is not available for at least one of the given attribute then returns with an error without changing any property value.

Parameters

property	[in] The new value of the property.
attrHeaders	[in] The array of attributes, that the property should be available for.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Inexistent property item.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of a specified attribute on a teamwork server.
• APIERR_READONLY - Tried to modify a read-only property (for example a property coming from a hotlink).
• APIERR_BADPROPERTY - The property definition is not available for one of the given attributes.

ACAPI_Attribute_Move()

GSErrCode __ACENV_CALL ACAPI_Attribute_Move	(	const GS::Array< API_AttributeFolder > &	foldersToMove,
		const GS::Array< GS::Guid > &	attributesToMove,
		const API_AttributeFolder &	targetFolder
	)

Moves attributes and attribute folders.

Since

Archicad 26

Parameters

foldersToMove	[in] List of folders to move.
attributesToMove	[in] List of attributes to move.
targetFolder	[in] Target folder, i.e. the new parent of the folders and attributes to move.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect typeID was specified.

Remarks

All folders (items of foldersToMove and targetFolder) have to be existing folders. Handling name collisions:

• If there are name collisions, the moved folders will be merged with the colliding folders in targetFolder, like in a filesystem.
• Name collision of folders is case insensitive. An existing folder in targetFolder will not be renamed. E.g. merging 'foo' into an existing 'Foo' keeps the 'Foo' name.
• Name collision between two moved folders will be handled in order of appearance in foldersToMove. E.g. moving 'A/foo' and 'B/Foo' (in this order) to 'Bar' will result in 'Bar/foo', because 'foo' is first created in 'Bar', and then it is not renamed to 'Foo'. foldersToMove and attributesToMove can contain repeated items. Repeated items will be handled as if only the first occurrence would be present in the list. foldersToMove and attributesToMove can contain items which are already under targetFolder. Such items will be left in place. foldersToMove and attributesToMove can contain items which are under a folder to move. Such items will be ignored, as if they would not be on the list, and only the outermost folder will be moved. A folder or attribute cannot be moved out of its attribute type.

ACAPI_Attribute_RemoveClassificationItem()

GSErrCode __ACENV_CALL ACAPI_Attribute_RemoveClassificationItem	(	const API_Attr_Head &	attrHead,
		const API_Guid &	itemGuid
	)

Removes a classification from an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
itemGuid	[in] The guid of the classification item, that should be removed from the attribute.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_READONLY - The attribute can not be modified (i.e. from a hotlink) or you do not have the right to remove classifications from attributes in the current teamwork plan.
• APIERR_BADID - Inexistent classification item.
• APIERR_BADPARS - The attribute did not have the specified classification.

ACAPI_Attribute_RenameFolder()

GSErrCode __ACENV_CALL ACAPI_Attribute_RenameFolder	(	const API_AttributeFolder &	folder,
		const GS::UniString &	newName
	)

Deletes an attribute folder and all the folders and attributes it contains.

Since

Archicad 26

Parameters

folder	[in] The folder to rename.
newName	[in] The new name for the folder.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect folder was specified.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOACCESSRIGHT - User has no permission to rename folders under folder.typeID.
• APIERR_NOTMINE - Attribute type folder.typeID is not reserved.

Remarks

Folder has to be an existing folder identified by it's typeID, and path or guid.. Deletes all deletable attributes and folders the given folder contains. If an attribute is not deletable, the folders containing the attribute are not deleted. newName has to be legal, must not be empty, and must not begin or end with whitespace. Renames the specified folder (while preserving it's guid). The root folder can't be renamed, two folders in the same parent folder can't have the same name.

ACAPI_Attribute_Search()

GSErrCode __ACENV_CALL ACAPI_Attribute_Search

(

API_Attr_Head *

attrHead

)

Searches for an attribute by name.

Parameters

attrHead

[in/out] The attribute to search for, identified by the typeID and name or the guid fields of the header.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; attrHead
• APIERR_BADID - The attribute type is invalid
• APIERR_BADGUID - The attribute with the given guid doesn't exist
• APIERR_BADNAME - The attribute with the given name doesn't exist

Remarks

This function is used to search for an attribute by name or by GUID. Upon return, the index and other applicable fields of the header are set. The primary search criteria is the GUID, then the Unicode name (if present), then the name field of the header. This function cannot be used to search for pens; they don't have any name or GUID.

Example

API_Attribute attrib;
BNZeroMemory (&attrib, sizeof (API_Attribute));
 
/* find out the index of the "Wave" line type */
attrib.header.guid = GSGuid2APIGuid (GS::Guid ("35DE8210-A51E-43AE-9837-8CF3A01E8F63"));
 
GSErrCode err = ACAPI_Attribute_Search (&attrib.header);
if (err == NoError) {
    char msgStr[512];
    sprintf (msgStr, "[%d] %s", attrib.header.index, attrib.header.name);
    ACAPI_WriteReport (msgStr, true);
}

ACAPI_Attribute_SetProperties()

GSErrCode __ACENV_CALL ACAPI_Attribute_SetProperties	(	const API_Attr_Head &	attrHead,
		const GS::Array< API_Property > &	properties
	)

Sets the specified built-in properties for the given values on an attribute.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
properties	[in] Specifies the properties to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect attributeTypeID or attributeIndex was specified or one of the property definitions' guid did not refer to a valid object.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of the specified attribute on a teamwork server.
• APIERR_READONLY - Tried to modify a read-only property (for example a property coming from a hotlink).
• APIERR_BADPROPERTY - The property definition is not available for the given attribute.

Example

GSErrCode SetAllPropertyValuesToDefault (API_AttrTypeID attributeTypeID, short attributeIndex)
{
    API_Attr_Head                     attributeHeader = {};
    GS::Array<API_PropertyDefinition> definitions;
 
    attributeHeader.typeID = attributeTypeID;
    attributeHeader.index = attributeIndex;
 
    GSErrCode error = ACAPI_Attribute_GetPropertyDefinitions (attributeHeader, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            API_Property property;
            property.definition = definitions[i];
            properties.Push (property);
        }
 
        error = ACAPI_Attribute_GetProperties (attributeHeader, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                properties[i].isDefault = true;
            }
            error = ACAPI_Attribute_SetProperties (attributeHeader, properties);
        }
    }
 
    return error;
}

ACAPI_Attribute_SetProperty()

GSErrCode __ACENV_CALL ACAPI_Attribute_SetProperty	(	const API_Attr_Head &	attrHead,
		const API_Property &	property
	)

Sets the property value of the property definition.

Parameters

attrHead	[in] Header of the attribute. The attribute is identified by typeID and index
property	[in] Property.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - The attrHead did not refer to a valid attribute.
• APIERR_NOACCESSRIGHT - The property can not be modified because you do not have the right to classify attributes in the current teamwork plan.
• APIERR_READONLY - The proeprty can not be modified because it is readonly.
• APIERR_BADID - Inexistent propert item.
• APIERR_GENERAL - Every other case.

ACAPI_CreateAttributeIndex()

API_AttributeIndex ACAPI_CreateAttributeIndex ( Int32  index )

inline

A wrapper function to create an API_AttributeIndex from its GS equivalent.

Since

Archicad 27

Parameters

index

[in] The attribute index to convert.

Returns

The API equivalent.

ACAPI_DisposeAttrDefsHdls()

GSErrCode __ACENV_CALL ACAPI_DisposeAttrDefsHdls

(

API_AttributeDef *

defs

)

Frees the memory occupied by all of the attribute definition handles.

Parameters

defs	[in] Points to an API_AttributeDef structure which contains handles used for previous operations and not needed any more.

Returns

Remarks

This is the recommended way of disposing the attribute definition handles for compatibility reasons, as in a later version of the API the API_AttributeDef structure might change.

ACAPI_DisposeAttrDefsHdlsExt()

GSErrCode __ACENV_CALL ACAPI_DisposeAttrDefsHdlsExt

(

API_AttributeDefExt *

defs

)

Frees the memory occupied by all of the attribute definition handles.

Parameters

defs	[in] Points to an API_AttributeDefExt structure which contains handles used for previous operations and not needed any more.

Returns

Remarks

This is the recommended way of disposing the attribute definition handles for compatibility reasons, as in a later version of the API the API_AttributeDefExt structure might change.

ACAPI_Notification_CatchAttributeReplacement()

GSErrCode __ACENV_CALL ACAPI_Notification_CatchAttributeReplacement

(

APIAttributeReplacementHandlerProc *

handlerProc

)

Register or unregister your add-on to be notified if some attributes are deleted and replaced by other attributes.

Since

Archicad 25

Parameters

handlerProc

[in] The callback procedure to call when notifications are sent out on replacement of attributes. Specifying nullptr here means you don't need the notifications any more.

Returns

• NoError - The required operation finished successfully.

Remarks

This function enables the API tool add-on to catch the deletion and replacement of the attributes in the project. This operation can be done with the Delete and Replace option in the Attribute Manager dialog. If you do not need to catch the changes of default settings any longer, please remember to unregister by calling ACAPI_Notification_CatchAttributeReplacement for the required element type with nullptr in the handlerProc parameter.

Example

// -----------------------------------------------------------------------------
// Attribute replacement handler function
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL HandleAttributeReplacement (const API_AttributeReplaceIndexTable& table)
{
    char    msgStr[256];
 
    if (table.ContainsKey (API_AttrTypeID::API_BuildingMaterialID)) {
        for (const auto& entry : table[API_AttrTypeID::API_BuildingMaterialID]) {
            sprintf (msgStr, "Changed Material: old index = %d, new index = %d", *entry.key, *entry.value);
            ACAPI_WriteReport (msgStr, false);
        }
    }
 
    return NoError;
}   // HandleAttributeReplacement
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL    Initialize (void)
 
{
    GSErrCode err = ACAPI_Notification_CatchAttributeReplacement (HandleAttributeReplacement);
 
    return err;
}   // Initialize

ACAPI_UserData_GetUserData()

GSErrCode __ACENV_CALL ACAPI_UserData_GetUserData	(	API_Attr_Head *	attrHead,
		API_AttributeUserData *	userData
	)

Obtains the user data attached to an attribute.

Since

Archicad 27

Parameters

attrHead	[in] Header of the attribute (only fields typeID and index are used).
userData	[in/out] Pointer to the user data.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Any of the passed parameters is nullptr
• APIERR_BADPLATFORMSIGN - The user data contained platform sign is invalid (out of range)
• APIERR_MEMFULL - Out of memory
• APIERR_NOUSERDATA - No user data attached by the caller module

Remarks

This function is used to get the user attached data from an atribute. The typeID and index fields of the DDD record has to be filled to get the data attached to the attribute. The caller should not allocate the userData->dataHdl field. It's allocated by the function itself but should be destroyed after use by the caller! Use the ACAPI_UserData_SetUserData functions to push data into the attribute record.

ACAPI_UserData_SetUserData()

GSErrCode __ACENV_CALL ACAPI_UserData_SetUserData	(	API_Attr_Head *	attrHead,
		const API_AttributeUserData *	userData
	)

Attaches user data to an attribute, or deletes the attached data.

Parameters

attrHead	[in] The attribute to attach the user data to is defined by the typeID and index fields of the header.
userData	[in] The user data to store. If dataHdl is nullptr, then the function deletes the user data.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - A nullptr attrHead or userData pointer was passed.
• APIERR_BADPLATFORMSIGN - The platform sign in the user data is invalid (out of range).

Remarks

This function is used to attach user data to an an atribute, or to delete the attached information (if userData->dataHdl is nullptr. The caller is responsible for allocating and deleting the userData->dataHdl. You can safely destroy the passed handle after use, as it is copied into the internal database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

API2AC_AttrIndex()

ADB::AttributeIndex API2AC_AttrIndex ( const API_AttributeIndex &  apiIndex )

inline

Converts an API_AttributeIndex to ADB::AttributeIndex.

Since

Archicad 27

Parameters

apiIndex

[in]

Returns

• ADB::AttributeIndex