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.

Enumerator
API_ElemCategory_Undefined	(Undefined category)
API_ElemCategory_StructuralFunction	Structural Function category
API_ElemCategory_Position	Position category
API_ElemCategory_RenovationStatus	Renovation status category
API_ElemCategory_RenovationFilter	Renovation filter category
API_ElemCategory_BRI	(available only in GER localized version)

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_Category_GetElementCategories (&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_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_Category_GetElementCategories (&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;
GSErrCode err = NoError;
ACAPI_Category_GetElementCategories (&categoryList);
 
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
    if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position) {
        GS::Array<API_ElemCategoryValue> categoryValueList;
        ACAPI_Category_GetElementCategoryValues (&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;
GSErrCode err = NoError;
ACAPI_Category_GetElementCategories (&categoryList);
 
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
    if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position) {
        GS::Array<API_ElemCategoryValue> categoryValueList;
        ACAPI_Category_GetElementCategoryValues (&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_Category_GetElementCategories (&categoryList);
 
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
    if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position) {
        GS::Array<API_ElemCategoryValue> categoryValueList;
        ACAPI_Category_GetElementCategoryValues (&category, &categoryValueList);
        if (!categoryValueList.IsEmpty ()) {
            if (changeDefaults) {
                GSErrCode err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
                if (err != NoError)
                    ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
            } else {
                GSErrCode 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_Category_GetElementCategories (&categoryList);
 
categoryList.Enumerate ([&] (const API_ElemCategory& category) {
    if (category.categoryID == API_ElemCategory_StructuralFunction || category.categoryID == API_ElemCategory_Position) {
        GS::Array<API_ElemCategoryValue> categoryValueList;
        ACAPI_Category_GetElementCategoryValues (&category, &categoryValueList);
        if (!categoryValueList.IsEmpty ()) {
            if (changeDefaults) {
                GSErrCode err = ACAPI_Category_SetCategoryValueDefault (element.header.type, category, categoryValueList[categoryValueList.GetSize () - 1]);
                if (err != NoError)
                    ErrorBeep ("ACAPI_Category_SetCategoryValueDefault ()", err);
            } else {
                GSErrCode err = ACAPI_Category_SetCategoryValue (element.header.guid, category, categoryValueList[0]);
                if (err != NoError)
                    ErrorBeep ("ACAPI_Category_SetCategoryValue ()", err);
            }
        }
    }
});