Set the given category of an element.

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

 

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.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

elemCategoryValue or elemCategory is incorrect.

APIERR_BADID

Incorrect elemGuid was specified.

For other common API errors see the API Errors document.

 

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 APIDb_GetElementCategoryValuesID.

 

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_Element_SetCategoryValueDefault (element.header.typeID, element.header.variationID, category,   categoryValueList[categoryValueList.GetSize () - 1]);
                    if (err != NoError)
                        ErrorBeep ("ACAPI_Element_SetCategoryValueDefault ()", err);
                } else {
                    err = ACAPI_Element_SetCategoryValue (element.header.guid, category,    categoryValueList[0]);
                    if (err != NoError)
                        ErrorBeep ("ACAPI_Element_SetCategoryValue ()", err);
                }
            }
        }
    });

 

Requirements

Version: API 19 or later

Header: ACAPinc.h

See Also

API_Guid, API_ElemCategoryID, API_ElemCategory, API_ElemCategoryValue,
APIDb_GetElementCategoryValuesID,
Element Manager, API Functions