Returns the given category of the element.

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

 

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.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

elemCategoryValue is nullptr 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 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_Element_GetCategoryValueDefault (type, category, &elemCategoryValue);
                if (err == NoError)
                    Do_DumpElemCategoryValue (elemCategoryValue);
                else
                    ErrorBeep ("ACAPI_Element_GetCategoryValueDefault ()", err);
            } else {
                err = ACAPI_Element_GetCategoryValue (elemGuid, category, &elemCategoryValue);
                if (err == NoError)
                    Do_DumpElemCategoryValue (elemCategoryValue);
                else
                    ErrorBeep ("ACAPI_Element_GetCategoryValue ()", err);
            }
        }
    });
}

 

Requirements

Version: API 19 or later

Header: ACAPinc.h

See Also

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