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...
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...
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.
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.
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.
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.
A common header for all the attribute types. It contains information which applies to all the attribu...
Definition: APIdefs_Attributes.h:1861
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.
Describes the extended information for different attributes.
Definition: APIdefs_Attributes.h:2005
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:
Frees the memory occupied by all of the attribute definition handles.
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.
Returns the number of instances of a given type of attribute.
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:
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.
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.
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.
[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.
[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.
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.
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.
[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.
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.
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.
[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.
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.
[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.
[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.
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!
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.
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.
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.
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!.
[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. The attribute will be named according to uniStringNamePtr in API_Attribute, or name if the first was nullptr. 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.
[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. The attribute will be named according to uniStringNamePtr in API_Attribute, or name if the first was nullptr. 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.
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.
[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.
[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.
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.
[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.
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.
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.
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.
[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.
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.