ACAPI_​Element_​GetCategoryValueDefault

Returns the given category of the element.

    GSErrCode  ACAPI_Element_GetCategoryValueDefault (
        const API_ElemTypeID&       typeID,
        const API_ElemVariationID&  variationID,
        const API_ElemCategory&     elemCategory,
        API_ElemCategoryValue*      elemCategoryValue
    );

 

Parameters

typeID
[in] Type of the default element whose category you want to obtain.
variationID
[in] The element variation that distinguishes the element kinds of the same type.
elemCategory
[in] The category identified by guid or categoryID.
elemCategoryValue
[out] The category value informations to be retrieved.

 

Return Values

NoError
The function has completed with success.
APIERR_BADPARS
elemCategoryValue is nullptr or elemCategory is incorrect.
APIERR_BADID
Incorrect typeID or variationID was specified.

For other common API errors see the API Errors document.

 

Remarks

This function is used to get category information for a default 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_ElemTypeID& typeID, const API_ElemVariationID& variationID, 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 (typeID, variationID, 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_ElemTypeID, API_ElemCategoryID, API_ElemCategory, API_ElemCategoryValue,
Element Manager, API Functions