Sets the value of a property for multiple elements. If the property is not available for at least one of the given element then returns with an error without changing any property value.

    GSErrCode  ACAPI_ElementList_ModifyPropertyValue (
        const API_Property&            property,
        const GS::Array<API_Guid>&     elemGuids
    );

 

Parameters

property

[in] The new value of the property.

elemGuids

[in] The array of elements, whose property should be changed.

 

Return Values

NoError

The function has completed with success.

APIERR_BADID

One of the elemGuids did not refer to a valid element.

APIERR_NOACCESSRIGHT

The current user does not have the right to modify the properties of a specified element on a teamwork server.

APIERR_READONLY

Tried to modify a read-only property (for example a property coming from a hotlink).

APIERR_BADPROPERTY

The property definition is not available for one of the given elements.

For other common API errors see the API Errors document.

 

Example

GSErrCode GetElemCategoryValue (const API_Guid& elemGuid, API_ElemCategoryValue& catValue);

GSErrCode SetAllIntegerPropertiesTo42 (GS::Array<API_Guid> selectedElements)
{
    GSErroCode err = NoError;
    GS::Array<API_PropertyDefinition> definitions;
    ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);

    for (UIndex i = 0; i < definitions.GetSize (); ++i) {
        if (definitions[i].collectionType == API_PropertySingleCollectionType &&
                 definitions[i].valueType == API_PropertyIntegerValueType) {
            API_Property property;
            property.definition = definitions[i];
            property.value.singleVariant.variant.type = property.definition.valueType;
            property.value.singleVariant.variant.intValue = 42;
            property.isDefault = false;

            // remove the elements from the list, which the property is not available for
            // (if you don't remove them, APIERR_BADPROPERTY will be returned)
            GS::Array<API_Guid> filteredSelectedElements;

            for (UIndex i = 0; i < selectedElements.GetSize (); ++i) {
                API_ElemCategoryValue categoryValue;
                err = GetElemCategoryValue (selectedElements[i], categoryValue);
                if (err == NoError && property.definition.availability.Contains (categoryValue)) {
                    filteredSelectedElements.Push (selectedElements[i]);
                }
            }

            err = ACAPI_ElementList_ModifyPropertyValue (property, filteredSelectedElements);
            if (err != NoError) {
                return err;
            }
        }
    }
    return NoError;
}

        

For more detailed examples, please see the Property_Test add-on.

 

Requirements

Version: API 20 or later

Header: ACAPinc.h

 

See Also

Properties,
API Functions