Creates an attribute.
GSErrCode ACAPI_Attribute_Create ( API_Attribute* attribute, API_AttributeDef* defs );
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.
Return Values
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.
For other common API errors see the API Errors document.
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.
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);
Requirements
- Version: API 1.3 or later
- Header: ACAPinc.h
See Also
API_Attribute, API_AttributeDef,
ACAPI_DisposeAttrDefsHdls,
Attribute Manager, API Functions