Archicad 28 C++ API
Loading...
Searching...
No Matches
Classes | Enumerations | Functions
Categories

Functions related to creating, accessing and manipulating Categories and the category-related data of elements. More...

Classes

struct  API_ElemCategory
 Element category structure. More...
 
struct  API_ElemCategoryValue
 Element category value structure. More...
 

Enumerations

enum  API_ElemCategoryID {
  API_ElemCategory_Undefined = 0 , API_ElemCategory_StructuralFunction , API_ElemCategory_Position , API_ElemCategory_RenovationStatus ,
  API_ElemCategory_RenovationFilter , API_ElemCategory_BRI
}
 Type identifiers of element category types. More...
 

Functions

GSErrCode ACAPI_Category_GetElementCategories (GS::Array< API_ElemCategory > *categoryList)
 Returns the array of categories.
 
GSErrCode ACAPI_Category_GetElementCategoryValues (const API_ElemCategory *category, GS::Array< API_ElemCategoryValue > *categoryValueList)
 Returns the array of category values in the given category.
 
GSErrCode ACAPI_Category_GetCategoryValue (const API_Guid &elemGuid, const API_ElemCategory &elemCategory, API_ElemCategoryValue *elemCategoryValue)
 Returns the given category of the element.
 
GSErrCode ACAPI_Category_GetCategoryValueDefault (const API_ElemType &type, const API_ElemCategory &elemCategory, API_ElemCategoryValue *elemCategoryValue)
 Returns the given category of the element.
 
GSErrCode ACAPI_Category_SetCategoryValue (const API_Guid &elemGuid, const API_ElemCategory &elemCategory, const API_ElemCategoryValue &elemCategoryValue)
 Set the given category of an element.
 
GSErrCode ACAPI_Category_SetCategoryValueDefault (const API_ElemType &type, const API_ElemCategory &elemCategory, const API_ElemCategoryValue &elemCategoryValue)
 Set the given category of a default element.
 

Detailed Description

Functions related to creating, accessing and manipulating Categories and the category-related data of elements.

Enumeration Type Documentation

◆ API_ElemCategoryID

enum API_ElemCategoryID

Type identifiers of element category types.

Remarks
API_ElemCategoryID is used in element category (API_ElemCategory structure) as identifier.

Function Documentation

◆ ACAPI_Category_GetCategoryValue()

GSErrCode ACAPI_Category_GetCategoryValue ( const API_Guid &  elemGuid,
const API_ElemCategory &  elemCategory,
API_ElemCategoryValue *  elemCategoryValue 
)

Returns the given category of the element.

Parameters
elemGuid[in] Guid of the element whose category you want to obtain.
elemCategory[in] The category identified by guid or categoryID.
elemCategoryValue[out] The category value information to be retrieved.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - elemCategoryValue is nullptr or elemCategory is incorrect.
  • APIERR_BADID - Incorrect elemGuid was specified.
Remarks
This function is used to get category information for an element. For available category types check API_ElemCategoryID.
Example
// -----------------------------------------------------------------------------
// Dump element category value
// -----------------------------------------------------------------------------
void Do_DumpElemCategoryValue (const API_ElemCategoryValue& elemCategoryValue)
{
WriteReport (" %s : %s (%s)", GS::UniString (elemCategoryValue.category.name).ToCStr ().Get (), GS::UniString (elemCategoryValue.name).ToCStr ().Get (), APIGuidToString (elemCategoryValue.guid).ToCStr ().Get ());
}
// -----------------------------------------------------------------------------
// Dump element's categories
// -----------------------------------------------------------------------------
void Do_DumpElemCategories (const API_Guid& elemGuid, const API_ElemType& type, bool dumpDefaults)
{
GSErrCode err = NoError;
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID != API_ElemCategory_BRI) {
API_ElemCategoryValue elemCategoryValue;
if (dumpDefaults) {
err = ACAPI_Category_GetCategoryValueDefault (type, category, &elemCategoryValue);
if (err == NoError)
Do_DumpElemCategoryValue (elemCategoryValue);
else
ErrorBeep ("ACAPI_Category_GetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_GetCategoryValue (elemGuid, category, &elemCategoryValue);
if (err == NoError)
Do_DumpElemCategoryValue (elemCategoryValue);
else
ErrorBeep ("ACAPI_Category_GetCategoryValue ()", err);
}
}
});
}
APIGuidToString
GS::UniString APIGuidToString(const API_Guid &guid)
Converting the API_Guid to a GS::UniString.
Definition: API_Guid.hpp:128
API_ElemCategory
Element category structure.
Definition: APIdefs_Elements.h:24848
API_ElemCategory::categoryID
API_ElemCategoryID categoryID
Identifier of the category.
Definition: APIdefs_Elements.h:24860
API_ElemCategory::name
GS::uchar_t name[API_UniLongNameLen]
Localized name of the category.
Definition: APIdefs_Elements.h:24866
API_ElemCategoryValue
Element category value structure.
Definition: APIdefs_Elements.h:24882
API_ElemCategoryValue::guid
API_Guid guid
GUID of the category value.
Definition: APIdefs_Elements.h:24888
API_ElemCategoryValue::name
GS::uchar_t name[API_UniLongNameLen]
Localized name of the category value.
Definition: APIdefs_Elements.h:24900
API_ElemCategoryValue::category
API_ElemCategory category
the category of the category value
Definition: APIdefs_Elements.h:24894
API_ElemType
The type of an element.
Definition: APIdefs_Elements.h:205
API_Guid
Represents a GS::Guid in the API layer.
Definition: API_Guid.hpp:46

◆ ACAPI_Category_GetCategoryValueDefault()

GSErrCode ACAPI_Category_GetCategoryValueDefault ( const API_ElemType &  type,
const API_ElemCategory &  elemCategory,
API_ElemCategoryValue *  elemCategoryValue 
)

Returns the given category of the element.

Since
Archicad 26
Parameters
type[in] Type of the default element whose category you want to obtain.
elemCategory[in] The category identified by guid or categoryID.
elemCategoryValue[out] The category value informations to be retrieved.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - elemCategoryValue is nullptr or elemCategory is incorrect.
  • APIERR_BADID - Incorrect type was specified.
Remarks
This function is used to get category information for a default element. For available category types check API_ElemCategoryID. typeID variationID API_ElemType
Example
// -----------------------------------------------------------------------------
// Dump element category value
// -----------------------------------------------------------------------------
void Do_DumpElemCategoryValue (const API_ElemCategoryValue& elemCategoryValue)
{
WriteReport (" %s : %s (%s)", GS::UniString (elemCategoryValue.category.name).ToCStr ().Get (), GS::UniString (elemCategoryValue.name).ToCStr ().Get (), APIGuidToString (elemCategoryValue.guid).ToCStr ().Get ());
}
// -----------------------------------------------------------------------------
// Dump element's categories
// -----------------------------------------------------------------------------
void Do_DumpElemCategories (const API_Guid& elemGuid, const API_ElemType& type, bool dumpDefaults)
{
GSErrCode err = NoError;
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID != API_ElemCategory_BRI) {
API_ElemCategoryValue elemCategoryValue;
if (dumpDefaults) {
err = ACAPI_Category_GetCategoryValueDefault (type, category, &elemCategoryValue);
if (err == NoError)
Do_DumpElemCategoryValue (elemCategoryValue);
else
ErrorBeep ("ACAPI_Category_GetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_GetCategoryValue (elemGuid, category, &elemCategoryValue);
if (err == NoError)
Do_DumpElemCategoryValue (elemCategoryValue);
else
ErrorBeep ("ACAPI_Category_GetCategoryValue ()", err);
}
}
});
}

◆ ACAPI_Category_GetElementCategories()

GSErrCode ACAPI_Category_GetElementCategories ( GS::Array< API_ElemCategory > *  categoryList)

Returns the array of categories.

Parameters
categoryList[out] The array of categories.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - categoryList is nullptr.
Example
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID
, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position || category.categoryID == API_ElemCategory_ElementClassification) {
GS::Array<API_ElemCategoryValue> categoryValueList;
ACAPI_Database (APIDb_GetElementCategoryValuesID, (void*) &category, &categoryValueList);
if (!categoryValueList.IsEmpty ()) {
if (changeDefaults) {
err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_SetCategoryValue (element.header.guid, category, categoryValueList[0]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValue ()", err);
}
}
}
});

◆ ACAPI_Category_GetElementCategoryValues()

GSErrCode ACAPI_Category_GetElementCategoryValues ( const API_ElemCategory *  category,
GS::Array< API_ElemCategoryValue > *  categoryValueList 
)

Returns the array of category values in the given category.

Parameters
category[in] The category identified by guid or categoryID.
categoryValueList[out] The array of category values.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - categoryList is nullptr.
  • APIERR_BADID - Incorrect category was specified (bad guid and categoryID).
Example
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position || category.categoryID == API_ElemCategory_ElementClassification) {
GS::Array<API_ElemCategoryValue> categoryValueList;
ACAPI_Database (APIDb_GetElementCategoryValuesID
, (void*) &category, &categoryValueList);
if (!categoryValueList.IsEmpty ()) {
if (changeDefaults) {
err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_SetCategoryValue (element.header.guid, category, categoryValueList[0]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValue ()", err);
}
}
}
});

◆ ACAPI_Category_SetCategoryValue()

GSErrCode ACAPI_Category_SetCategoryValue ( const API_Guid &  elemGuid,
const API_ElemCategory &  elemCategory,
const API_ElemCategoryValue &  elemCategoryValue 
)

Set the given category of an element.

Parameters
elemGuid[in] GUID of the element.
elemCategory[in] The category identified by guid or categoryID.
elemCategoryValue[in] The category value informations to be set.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - elemCategoryValue or elemCategory is incorrect.
  • APIERR_BADID - Incorrect elemGuid was specified.
Remarks
This function is used to set category information for an element. For available category types see API_ElemCategoryID. To get the list of category values in a given category use ACAPI_Category_GetElementCategoryValues.
Example
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position || category.categoryID == API_ElemCategory_ElementClassification) {
GS::Array<API_ElemCategoryValue> categoryValueList;
ACAPI_Database (APIDb_GetElementCategoryValuesID, (void*) &category, &categoryValueList);
if (!categoryValueList.IsEmpty ()) {
if (changeDefaults) {
err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_SetCategoryValue (element.header.guid, category, categoryValueList[0]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValue ()", err);
}
}
}
});

◆ ACAPI_Category_SetCategoryValueDefault()

GSErrCode ACAPI_Category_SetCategoryValueDefault ( const API_ElemType &  type,
const API_ElemCategory &  elemCategory,
const API_ElemCategoryValue &  elemCategoryValue 
)

Set the given category of a default element.

Since
Archicad 26
Parameters
type[in] Type of the default element.
elemCategory[in] The category identified by guid or categoryID.
elemCategoryValue[in] The category value informations to be set.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - elemCategoryValue or elemCategory is incorrect.
  • APIERR_BADID - Incorrect type was specified.
Remarks
This function is used to set category information for a default element. For available category types see API_ElemCategoryID. To get the list of category values in a given category use ACAPI_Category_GetElementCategoryValues. From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.
Example
GS::Array<API_ElemCategory> categoryList;
ACAPI_Database (APIDb_GetElementCategoriesID, &categoryList);
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position || category.categoryID == API_ElemCategory_ElementClassification) {
GS::Array<API_ElemCategoryValue> categoryValueList;
ACAPI_Database (APIDb_GetElementCategoryValuesID, (void*) &category, &categoryValueList);
if (!categoryValueList.IsEmpty ()) {
if (changeDefaults) {
err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
} else {
err = ACAPI_Category_SetCategoryValue (element.header.guid, category, categoryValueList[0]);
if (err != NoError)
ErrorBeep ("ACAPI_Category_SetCategoryValue ()", err);
}
}
}
});