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



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


Return Values

The function has completed with success.
One of the elemGuids did not refer to a valid element.
The current user does not have the right to modify the properties of a specified element on a teamwork server.
Tried to modify a read-only property (for example a property coming from a hotlink).
The property definition is not available for one of the given elements.

For other common API errors see the API Errors document.



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.



Version: API 20 or later
Header: ACAPinc.h


See Also

API Functions