ACAPI_​Attribute_​Create

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