Property Manager

Functions related to accessing and manipulating Properties and the category-related data of elements and attributes. More...

Classes
struct	API_Variant
	A container that can store different types of data. More...
struct	API_SingleVariant
	A container for storing a single value. More...
struct	API_ListVariant
	A container for storing a list of values. More...
struct	API_SingleEnumerationVariant
	A container for storing a single value from a list of allowed values. More...
struct	API_PropertyValue
	A container for storing a property's value. More...
struct	API_PropertyDefaultValue
	A structure representing a property default value. More...
struct	API_PropertyGroup
	A structure representing a property group. More...
struct	API_PropertyDefinition
	A structure representing a property definition. More...
struct	API_Property
	A container that can store different types of data. More...
class	API_PropertyConversionUtilsInterface

Typedefs
typedef GSErrCode __ACENV_CALL	APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)
	Callback function to handle the different property assignments.
typedef bool __ACENV_CALL	APIPropertyVisibilityHandlerProc(API_PropertyVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &propertyDefinitionGuid)
	Callback function to handle the visibility of a property.

Enumerations
enum	API_VariantStatus { API_VariantStatusNull , API_VariantStatusUserUndefined , API_VariantStatusNormal }
	Describes the status of a variant value.

Functions
GSErrCode __ACENV_CALL	ACAPI_Property_CheckPropertyExpressionString (GS::UniString *expressionString)
	Checks if the given property expression is a syntactically valid one.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyExprReferenceString (API_PropertyDefinition *propertyDefinition, GS::UniString *propertyReferenceString)
	Returns the string that can be used in expressions to refer to a specific property.
GSErrCode __ACENV_CALL	ACAPI_Property_RegisterPropertyObjectHandler (short assignStrResID)
	Registers a property handler.
GSErrCode __ACENV_CALL	ACAPI_Property_RegisterPropertyVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify property visibility.
GSErrCode __ACENV_CALL	ACAPI_Property_InstallPropertyObjectHandler (short strResID, APIPropertyObjectCommandProc *propertyCommandProc)
	Installs the property handler function for the given menu item.
GSErrCode __ACENV_CALL	ACAPI_Property_InstallPropertyVisibilityHandler (APIPropertyVisibilityHandlerProc *handlerProc)
	Installs the property visibility handler function.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyObjects (const API_Elem_Head *elemHead, API_PropertyObjectRefType ***propRefs, Int32 *nProp)
	Returns property objects of the element.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyDefinitions (const API_Guid &elemGuid, API_PropertyDefinitionFilter filter, GS::Array< API_PropertyDefinition > &propertyDefinitions)
	Retrieves all of the property definitions that are available for an element.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValue (const API_Guid &elemGuid, const API_Guid &propertyDefinitionGuid, API_Property &property)
	Retrieves the specified property definition's value from the element.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValues (const API_Guid &elemGuid, const GS::Array< API_PropertyDefinition > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the specified property definitions with values.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValuesByGuid (const API_Guid &elemGuid, const GS::Array< API_Guid > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the specified property definitions (defined by their GUIDs) with values.
GSErrCode __ACENV_CALL	ACAPI_Element_SetProperty (const API_Guid &elemGuid, const API_Property &property)
	Sets the specified property for the given values on an element.
GSErrCode __ACENV_CALL	ACAPI_Element_SetProperties (const API_Guid &elemGuid, const GS::Array< API_Property > &properties)
	Sets the specified properties for the given values on an element.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (const API_ElemType &type, API_PropertyDefinitionFilter filter, GS::Array< API_PropertyDefinition > &definitions)
	Retrieves all of the property definitions that are available for an element default.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValueOfDefaultElem (const API_ElemType &type, const API_Guid &propertyDefinitionGuid, API_Property &property)
	Retrieves the value of the specified property definition.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValuesOfDefaultElem (const API_ElemType &type, const GS::Array< API_PropertyDefinition > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the values of the specified property definitions.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValuesOfDefaultElemByGuid (const API_ElemType &type, const GS::Array< API_Guid > &propertyDefinitionGuids, GS::Array< API_Property > &properties)
	Retrieves the values of the specified property definitions.
GSErrCode __ACENV_CALL	ACAPI_Element_SetPropertyOfDefaultElem (const API_ElemType &type, const API_Property &property)
	Sets the specified property to the given value on an element default.
GSErrCode __ACENV_CALL	ACAPI_Element_SetPropertiesOfDefaultElem (const API_ElemType &type, const GS::Array< API_Property > &properties)
	Sets the specified properties for the given values on an element default.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionValueEditable (const API_Guid &elemGuid, const API_Guid &propertyGuid)
	Tells whether the value of the property can be modified for the specified element. If the elemGuid argument is APINULLGuid, it tells whether the property definition's default value is editable.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionValueEditableDefault (const API_ElemType &type, const API_Guid &propertyGuid)
	Tells whether the value of the property can be modified for the specified tool default.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionAvailable (const API_Guid &elemGuid, const API_Guid &propertyGuid)
	Tells whether a property definition is available for an element.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionAvailableDefault (const API_ElemType &type, const API_Guid &propertyGuid)
	Tells whether a property definition is available for an element default.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionVisible (const API_Guid &elemGuid, const API_Guid &propertyGuid)
	Tells whether a property definition is visible for an element.
bool __ACENV_CALL	ACAPI_Element_IsPropertyDefinitionVisibleDefault (const API_ElemType &type, const API_Guid &propertyGuid)
	Tells whether a property definition is visible for an element default.
GSErrCode __ACENV_CALL	ACAPI_Property_AddProperty (API_PropertyDefinition &definition, const GS::Array< API_Guid > &elemGuids)
	Makes a property definition available for all of given elements (it is created if it does not exist).
GSErrCode __ACENV_CALL	ACAPI_Property_ModifyPropertyValue (const API_Property &property, const GS::Array< API_Guid > &elemGuids)
	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 __ACENV_CALL	ACAPI_Property_DeleteProperty (const API_Guid &definitionGuid, const GS::Array< API_Guid > &elemGuids)
	Makes a property definition unavailable for all of given elements.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyDefinitions (const API_ElemComponentID &elemComponent, API_PropertyDefinitionFilter filter, GS::Array< API_PropertyDefinition > &propertyDefinitions)
	Retrieves all of the property definitions that are available for a component of an element.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValue (const API_ElemComponentID &elemComponent, const API_Guid &propertyDefinitionGuid, API_Property &property)
	Retrieves the specified property definition's value from the component.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValues (const API_ElemComponentID &elemComponent, const GS::Array< API_PropertyDefinition > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the values of the specified property definitions from the component.
GSErrCode __ACENV_CALL	ACAPI_Element_GetPropertyValuesByGuid (const API_ElemComponentID &elemComponent, const GS::Array< API_Guid > &propertyDefinitions, GS::Array< API_Property > &properties)
	Retrieves the specified property definitions (defined by their GUIDs) with values from the component.
GSErrCode __ACENV_CALL	ACAPI_Notification_PropertyVisibilityChanged ()
	Sends out an APINotify_PropertyVisibilityChanged project event notification to the other add-ons to state that at least one property's visibility has changed.
GSErrCode __ACENV_CALL	ACAPI_ActivatePropertyObjectHandler (short strResID, bool active)
	Activates or deactivates an add-on's property handler.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyGroups (GS::Array< API_PropertyGroup > &groups)
	Retrieves all the property groups.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyDefinitions (const API_Guid &groupGuid, GS::Array< API_PropertyDefinition > &definitions)
	Retrieves all the property definitions from a given group.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyGroup (API_PropertyGroup &group)
	Retrieves one property group identified by its guid.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyDefinition (API_PropertyDefinition &definition)
	Retrieves one property definition identified by its guid.
GSErrCode __ACENV_CALL	ACAPI_Property_CreatePropertyGroup (API_PropertyGroup &group)
	Creates a property group in the current plan.
GSErrCode __ACENV_CALL	ACAPI_Property_CreatePropertyDefinition (API_PropertyDefinition &definition)
	Creates a property definition in the current plan.
GSErrCode __ACENV_CALL	ACAPI_Property_ChangePropertyGroup (const API_PropertyGroup &group)
	Changes an already existing property group in the current plan (identified by its guid).
GSErrCode __ACENV_CALL	ACAPI_Property_ChangePropertyDefinition (const API_PropertyDefinition &definition)
	Changes an already existing property definition in the current plan (identified by its guid).
bool __ACENV_CALL	ACAPI_Property_IsValidValue (const API_PropertyValue &value, const API_PropertyDefinition &definition)
	Returns true if the value is acceptable for the given property definition.
GSErrCode __ACENV_CALL	ACAPI_Property_DeletePropertyGroup (const API_Guid &groupGuid)
	Deletes a property group and all of the property definitions inside in the current plan.
GSErrCode __ACENV_CALL	ACAPI_Property_DeletePropertyDefinition (const API_Guid &propertyGuid)
	Deletes a property definition in the current plan.
GSErrCode __ACENV_CALL	ACAPI_Property_Import (const GS::UniString &propertyXml, API_PropertyDefinitionNameConflictResolutionPolicy conflictPolicy)
	Imports a property xml.
GSErrCode __ACENV_CALL	ACAPI_Property_GetPropertyValueString (const API_Property &apiProperty, GS::UniString *resultString)
	Convert an API property value to display string.
GSErrCode __ACENV_CALL	ACAPI_Property_SetPropertyValueFromString (const GS::UniString &propertyValueString, const API_PropertyConversionUtilsInterface &conversionUtils, API_Property *property)
	Sets the value of a property value from a passed string.

Detailed Description

Functions related to accessing and manipulating Properties and the category-related data of elements and attributes.

Properties

Overview

This feature of the Archicad allows one to store user-defined name-value pairs for Model elements. The keys (names) of the properties are represented with API_PropertyDefinition, that are stored per project, not per element. The definitions are part of a two-level deep tree structure. On the top level there are API_PropertyGroup, which are a collection of definitions with a unique name. The definitions' name also has to be unique within its group.

The definitions also have descriptions and they store the value type (e.g int, double) and collection type (e.g single value, list) of the data it can store. If a definition is made available for a classification, then all the elements in that classification will have that property - initially with a default value, that is part of the definition.

Properties can also have an enumerated collection type, which means that their values are limited to a finite number of predefined valid values. In this case these predefined values are part of the definition

Handler functions

Please refer to the functions below the header of a thematic group to get details on that topic.

The following functions let you manipulate API_PropertyGroup.

• ACAPI_Property_ChangePropertyGroup
• ACAPI_Property_CreatePropertyGroup
• ACAPI_Property_DeletePropertyGroup
• ACAPI_Property_GetPropertyGroup
• ACAPI_Property_GetPropertyGroups
• ACAPI_Property_Import

The following functions let you manipulate API_PropertyDefinition

• ACAPI_Property_ChangePropertyDefinition
• ACAPI_Property_CreatePropertyDefinition
• ACAPI_Property_DeletePropertyDefinition
• ACAPI_Property_GetPropertyDefinition
• ACAPI_Property_GetPropertyDefinitions
• ACAPI_Property_IsValidValue

The following functions let you manipulate API_PropertyDefinition attached to elements.

• ACAPI_Element_GetPropertyDefinitions
• ACAPI_Element_GetPropertyValuesOfDefaultElem
• ACAPI_Element_IsPropertyDefinitionAvailable
• ACAPI_Element_IsPropertyDefinitionAvailableDefault
• ACAPI_Element_IsPropertyDefinitionVisible
• ACAPI_Element_IsPropertyDefinitionVisibleDefault

The following functions let you manipulate API_PropertyValue attached to elements.

• ACAPI_Element_GetPropertyValues
• ACAPI_Element_GetPropertyValuesByGuid
• ACAPI_Element_SetProperties
• ACAPI_Element_SetPropertiesOfDefaultElem
• ACAPI_Element_SetProperty
• ACAPI_Element_IsPropertyDefinitionAvailable
• ACAPI_Element_IsPropertyDefinitionAvailableDefault
• ACAPI_Element_IsPropertyDefinitionValueEditable
• ACAPI_Element_IsPropertyDefinitionValueEditableDefault

The following functions let you to efficiently manipulate properties for a list of elements.

• ACAPI_Property_AddProperty
• ACAPI_Property_ModifyPropertyValue
• ACAPI_Property_DeleteProperty

The following functions let you manipulate the properties of the attributes

• ACAPI_Attribute_GetPropertyDefinitions
• ACAPI_Attribute_GetPropertyValue
• ACAPI_Attribute_GetPropertyValues
• ACAPI_Attribute_GetPropertyValuesByGuid
• ACAPI_Attribute_SetProperty
• ACAPI_Attribute_SetProperties
• ACAPI_Attribute_IsPropertyDefinitionValueEditable
• ACAPI_Attribute_IsPropertyDefinitionAvailable
• ACAPI_Attribute_IsPropertyDefinitionVisible

Typedef Documentation

APIPropertyObjectCommandProc

typedef GSErrCode __ACENV_CALL APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)

Callback function to handle the different property assignments.

Parameters

propertyParams

[in] the parameters of the property assignment.

Returns

• NoError - The function has completed with success.

APIPropertyVisibilityHandlerProc

typedef bool __ACENV_CALL APIPropertyVisibilityHandlerProc(API_PropertyVisibilityMode visibilityMode, const GS::Array< API_Guid > &classificationGuids, const API_Guid &propertyDefinitionGuid)

Callback function to handle the visibility of a property.

Parameters

visibilityMode	[in] specifies what should the callback function return. Has one of the following values: API_PropertyVisibilityMode Meaning APIPropVis_IsEnabled The callback function should return true if the visibility handling is enabled. APIPropVis_IsPropertyVisible The callback function should return true if the given property is visible.
classificationGuids	[in] the classification guids of the current element.
propertyDefinitionGuid	[in] the guid of the current property.

Returns

• bool - The result.

Function Documentation

ACAPI_ActivatePropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_ActivatePropertyObjectHandler	(	short	strResID,
		bool	active
	)

Activates or deactivates an add-on's property handler.

Parameters

strResID	[in] tells for which property handler is this command issued
active	[in] turns the property handler on/off

Returns

• NoError - The function has completed with success.

Remarks

Only one property handler can be active in Archicad at a time. The return value of this functions depends on the user, as a dialog pops up when you issue this command. When the function returns, you should adjust your menu items accordingly. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

if (ACAPI_ActivatePropertyObjectHandler (stringResID, !checkedAssignProperty) == NoError) {
 
    checkedAssignProperty = !checkedAssignProperty;
 
    API_MenuItemRef mir;
    Int32           flags;
 
    BNZeroMemory (&mir, sizeof (API_MenuItemRef));
    mir.menuResID = menuResID;
    mir.itemIndex = 1;
    ACAPI_Interface (APIIo_GetMenuItemFlagsID, &mir, &flags);
    if (checkedAssignProperty)
        flags = flags | API_MenuItemChecked;
    else
        flags = flags & !API_MenuItemChecked;
 
    ACAPI_Interface (APIIo_SetMenuItemFlagsID, &mir, &flags);
}

ACAPI_Element_GetPropertyDefinitions() [1/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyDefinitions	(	const API_ElemComponentID &	elemComponent,
		API_PropertyDefinitionFilter	filter,
		GS::Array< API_PropertyDefinition > &	propertyDefinitions
	)

Retrieves all of the property definitions that are available for a component of an element.

Parameters

elemComponent	[in] The identifier of the element's component to search for.
filter	[in] Filter the list of property definitions (API_PropertyDefinitionFilter_UserDefined, API_PropertyDefinitionFilter_BuiltIn, API_PropertyDefinitionFilter_All).
propertyDefinitions	[out] Array of property definitions that are available for the given component.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The value of elemComponent did not refer to a valid component.

Example

GSErrCode GetPropertyDefinitionNames (const API_ElemComponentID& elemComponent, GS::Array<GS::UniString>& names)
{
    GS::Array<API_PropertyDefinition> definitions;
    const GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemComponent, API_PropertyDefinitionFilter_All, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            names.Push (definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyDefinitions() [2/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyDefinitions	(	const API_Guid &	elemGuid,
		API_PropertyDefinitionFilter	filter,
		GS::Array< API_PropertyDefinition > &	propertyDefinitions
	)

Retrieves all of the property definitions that are available for an element.

Parameters

elemGuid	[in] The element's identifier to search for.
filter	[in] Filter the list of property definitions (API_PropertyDefinitionFilter_UserDefined, API_PropertyDefinitionFilter_FundamentalBuiltIn, API_PropertyDefinitionFilter_UserLevelBuiltIn, API_PropertyDefinitionFilter_All).
propertyDefinitions	[out] Array of property definitions that are available for a classification of the given element.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.

Example

GSErrCode GetPropertyDefinitionNames (const API_Guid& elemGuid, GS::Array<GS::UniString>& names)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            names.Push (definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyDefinitionsOfDefaultElem()

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyDefinitionsOfDefaultElem	(	const API_ElemType &	type,
		API_PropertyDefinitionFilter	filter,
		GS::Array< API_PropertyDefinition > &	definitions
	)

Retrieves all of the property definitions that are available for an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
filter	[in] The property definition type to filter for.
definitions	[out] Array of property definitions that are available for a classification of the given element default.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetPropertyDefinitionNames (const API_ElemType& type, GS::Array<GS::UniString>& names)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            names.Push(definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyObjects()

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyObjects	(	const API_Elem_Head *	elemHead,
		API_PropertyObjectRefType ***	propRefs,
		Int32 *	nProp
	)

Returns property objects of the element.

Parameters

elemHead	[in] The element to get the properties for.
propRefs	[out] List of property objects.
nProp	[out] Number of the property objects.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - propRefs or nProp is nullptr
• APIERR_BADID - Incorrect elemHead was specified
• APIERR_MEMFULL - Not enough memory to get the properties

Remarks

This function is used to get the list of property objects for a linked element. The properties can be associated with construction elements by criteria or by individual direct assignment. This applies to all construction elements. From Archicad 9 the linked properties of both an element instance and the element defaults can be accessed with two new functions: ACAPI_ElementLink_GetLinkedPropertyObjects and ACAPI_ElementLink_SetLinkedPropertyObjects.

Example

void GetProperties (const API_Guid& guid)
{
    API_Elem_Head              elemHead;
    API_PropertyObjectRefType  **propRefs;
    API_LibPart                libPart;
    Int32                      nProp, i;
    char                       s[256];
    GSErrCode                  err;
 
    BNZeroMemory (&elemHead, sizeof (API_Elem_Head));
    elemHead.guid = guid;
 
    err = ACAPI_Element_GetPropertyObjects (&elemHead, &propRefs, &nProp);
    if (err == NoError) {
        for (i = 0; i < nProp; i++) {
            BNZeroMemory (&libPart, sizeof (API_LibPart));
            libPart.index = (*propRefs)[i].libIndex;
            err = ACAPI_LibraryPart_Get (&libPart);
            if (err == NoError) {
                if ((*propRefs)[i].assign)
                    sprintf (s, "Associated property:");
                else
                    sprintf (s, "Property by criteria:");
                sprintf (s, "%s %s", s, (const char *) GS::UniString (libPart.docu_UName).ToCStr ());
                ACAPI_WriteReport (s, false);
            }
        }
        BMKillHandle ((GSHandle *) &propRefs);
    }
}

ACAPI_Element_GetPropertyValue() [1/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValue	(	const API_ElemComponentID &	elemComponent,
		const API_Guid &	propertyDefinitionGuid,
		API_Property &	property
	)

Retrieves the specified property definition's value from the component.

Parameters

elemComponent	[in] The identifier of the element's component to search for.
propertyDefinitionGuid	[in] The property definition to get the values for.
property	[out] The value of the requested property.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemComponent did not refer to a valid component.
• APIERR_GENERAL - The propertyDefinitionGuid did not refer to a valid property definition.

Example

GSErrCode GetPropertyValue (const API_ElemComponentID& elemComponent, API_PropertyValue& value)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemComponent, API_PropertyDefinitionFilter_All, definitions);
    if (error == NoError && !definitions.IsEmpty ()) {
        API_Property property = {};
        error = ACAPI_Element_GetPropertyValue (elemComponent, definitions[0].guid, property);
        if (error == NoError) {
            value = property.value;
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValue() [2/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValue	(	const API_Guid &	elemGuid,
		const API_Guid &	propertyDefinitionGuid,
		API_Property &	property
	)

Retrieves the specified property definition's value from the element.

Parameters

elemGuid	[in] The element GUID to search for.
propertyDefinitionGuid	[in] The property definition to get the values for.
property	[out] The value of the requested property.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.
• APIERR_GENERAL - The propertyDefinitionGuid did not refer to a valid property definition.

Example

GSErrCode GetPropertyValue (const API_Guid& elemGuid, API_PropertyValue& value)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        API_Property  property = {};
        error = ACAPI_Element_GetPropertyValue (elemGuid, definitions[0].guid, property);
        if (error == NoError) {
            value = property;
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValueOfDefaultElem()

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValueOfDefaultElem	(	const API_ElemType &	type,
		const API_Guid &	propertyDefinitionGuid,
		API_Property &	property
	)

Retrieves the value of the specified property definition.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyDefinitionGuid	[in] The property definition's GUID to get the value for.
property	[out] The value of the requested property.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetPropertyValue (const API_ElemType& type, API_PropertyValue& value)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError && definitions.GetSize () > 0) {
        API_Property property = {};
        error = ACAPI_Element_GetPropertyValueOfDefaultElem (type, definitions[0].guid, property);
        if (error == NoError) {
            value = property;
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValues() [1/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValues	(	const API_ElemComponentID &	elemComponent,
		const GS::Array< API_PropertyDefinition > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the values of the specified property definitions from the component.

Parameters

elemComponent	[in] The identifier of the element's component to search for.
propertyDefinitions	[in] The property definitions to get the values for.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemComponent did not refer to a valid element.

Example

GSErrCode GetAllPropertyValues (const API_ElemComponentID& elemComponent, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemComponent, API_PropertyDefinitionFilter_All, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValues (elemComponent, definitions, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue.basicValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValues() [2/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValues	(	const API_Guid &	elemGuid,
		const GS::Array< API_PropertyDefinition > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the specified property definitions with values.

Parameters

elemGuid	[in] The element GUID to search for.
propertyDefinitions	[in] The property definitions to get the values for. They are identified through definition.guid.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.

Example

GSErrCode GetAllPropertyValues (const API_Guid& elemGuid, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Property>  properties;
        error = ACAPI_Element_GetPropertyValues (elemGuid, definitions, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesByGuid() [1/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValuesByGuid	(	const API_ElemComponentID &	elemComponent,
		const GS::Array< API_Guid > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the specified property definitions (defined by their GUIDs) with values from the component.

Parameters

elemComponent	[in] The identifier of the element's component to search for.
propertyDefinitions	[in] The property definition GUIDs to get the values for.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemComponent did not refer to a valid element.

Example

GSErrCode GetAllPropertyValues (const API_ElemComponentID& elemComponent, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemComponent, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Guid> propertyDefinitionGuids;
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            propertyDefinitionGuids.Push (definitions[i].guid);
        }
        GS::Array<API_Property>  properties;
        error = ACAPI_Element_GetPropertyValuesByGuid (elemComponent, propertyDefinitionGuids, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue.basicValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesByGuid() [2/2]

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValuesByGuid	(	const API_Guid &	elemGuid,
		const GS::Array< API_Guid > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the specified property definitions (defined by their GUIDs) with values.

Parameters

elemGuid	[in] The element GUID to search for.
propertyDefinitions	[in] The property definition GUIDs to get the values for.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.

Example

GSErrCode GetAllPropertyValues (const API_Guid& elemGuid, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Guid> propertyDefinitionList;
        for (UInt32 i = 0; i (); i++) {
            if (ACAPI_Element_IsPropertyDefinitionVisible (elemGuid, definitions[i].guid)) {
                propertyDefinitionList.Push (definitions[i].guid);
            }
        }
        GS::Array<API_Property>  properties;
        error = ACAPI_Element_GetPropertyValuesByGuid (elemGuid, propertyDefinitionList, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}
 
 
 
For more detailed examples, please see the Property_Test add-on.
 
    
Requirements
Version:
API 22 or later
Header:
ACAPinc.h
 
 
See Also
Properties
,
API Functions
 
 
Created on April 25, 2018

ACAPI_Element_GetPropertyValuesOfDefaultElem()

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValuesOfDefaultElem	(	const API_ElemType &	type,
		const GS::Array< API_PropertyDefinition > &	propertyDefinitions,
		GS::Array< API_Property > &	properties
	)

Retrieves the values of the specified property definitions.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyDefinitions	[in] The property definitions (identified by definition.guid) to get the values for.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetAllPropertyValues (const API_ElemType& type, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValuesOfDefaultElem (type, definitions, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesOfDefaultElemByGuid()

GSErrCode __ACENV_CALL ACAPI_Element_GetPropertyValuesOfDefaultElemByGuid	(	const API_ElemType &	type,
		const GS::Array< API_Guid > &	propertyDefinitionGuids,
		GS::Array< API_Property > &	properties
	)

Retrieves the values of the specified property definitions.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyDefinitionGuids	[in] The property definition GUIDs to get the values for.
properties	[out] The definitions and values of the requested properties.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetAllPropertyValuesByGuid (const API_ElemType& type, GS::Array<API_PropertyValue>& values)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsDefault (type, definitions);
    if (error == NoError) {
        GS::Array<API_Guid> propGuids;
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            propGuids.Push (definitions[i].guid);
        }
 
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValuesOfDefaultElemByGuid (type, propGuids, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                if (properties[i].isDefault) {
                    values.Push (properties[i].definition.defaultValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_IsPropertyDefinitionAvailable()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionAvailable	(	const API_Guid &	elemGuid,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is available for an element.

Parameters

elemGuid	[in] The element GUID to search for.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is available for the element.
• false - The given property definition is not available for the element.

Example

GSErrCode GetAvailablePropertyDefinitions (const API_Guid& elemGuid, GS::Array<API_PropertyDefinition>& availableProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Element_IsPropertyDefinitionAvailable (elemGuid, definitions[i].guid)) {
                availableProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_IsPropertyDefinitionAvailableDefault()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionAvailableDefault	(	const API_ElemType &	type,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is available for an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is available for the element default.
• false - The given property definition is not available for the element default.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetAvailablePropertyDefinitions (const API_ElemType& type, GS::Array<API_PropertyDefinition>& availableProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Element_IsPropertyDefinitionAvailableDefault (type, definitions[i].guid)) {
                availableProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_IsPropertyDefinitionValueEditable()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionValueEditable	(	const API_Guid &	elemGuid,
		const API_Guid &	propertyGuid
	)

Tells whether the value of the property can be modified for the specified element. If the elemGuid argument is APINULLGuid, it tells whether the property definition's default value is editable.

Parameters

elemGuid	[in] The element GUID to search for. It can be APINULLGuid, in this case the property definition's default value is checked.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The value of the property, or the property definition's default value can be modified.
• false - The value of the property, or the property definition's default value can not be modified. For example, it is a read-only property, or a User Defined property with expression, which has cyclic property references.

Example

GSErrCode GetEditablePropertyDefinitions (const API_Guid& elemGuid, GS::Array<API_PropertyDefinition>& editableProperties)
{
        GS::Array<API_PropertyDefinition> definitions;
        GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
        if (error == NoError) {
                for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
                        if (ACAPI_Element_IsPropertyDefinitionValueEditable (elemGuid, definitions[i].guid)) {
                                editableProperties.Push (definitions[i]);
                        }
                }
        }
        return error;
}

ACAPI_Element_IsPropertyDefinitionValueEditableDefault()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionValueEditableDefault	(	const API_ElemType &	type,
		const API_Guid &	propertyGuid
	)

Tells whether the value of the property can be modified for the specified tool default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The value of the property can be modified.
• false - The value of the property can not be modified. For example, it is a read-only property, or a User Defined property with expression, which has cyclic property references.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetAvailablePropertyDefinitions (const API_ElemType& type, GS::Array<API_PropertyDefinition>& editableProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Element_IsPropertyDefinitionValueEditableDefault (type, definitions[i].guid)) {
                editableProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_IsPropertyDefinitionVisible()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionVisible	(	const API_Guid &	elemGuid,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is visible for an element.

Parameters

elemGuid	[in] The element GUID to search for.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is visible for the element.
• false - The given property definition is not visible for the element.

Example

GSErrCode GetVisiblePropertyDefinitions (const API_Guid& elemGuid, GS::Array<API_PropertyDefinition>& visibleProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Element_IsPropertyDefinitionVisible (elemGuid, definitions[i].guid)) {
                visibleProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_IsPropertyDefinitionVisibleDefault()

bool __ACENV_CALL ACAPI_Element_IsPropertyDefinitionVisibleDefault	(	const API_ElemType &	type,
		const API_Guid &	propertyGuid
	)

Tells whether a property definition is visible for an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
propertyGuid	[in] The property definition GUID to search for.

Returns

• true - The given property definition is visible for the element default.
• false - The given property definition is not visible for the element default.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetVisiblePropertyDefinitions (const API_ElemType& type, GS::Array<API_PropertyDefinition>& visibleProperties)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); ++i) {
            if (ACAPI_Element_IsPropertyDefinitionVisibleDefault (type, definitions[i].guid)) {
                visibleProperties.Push (definitions[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_SetProperties()

GSErrCode __ACENV_CALL ACAPI_Element_SetProperties	(	const API_Guid &	elemGuid,
		const GS::Array< API_Property > &	properties
	)

Sets the specified properties for the given values on an element.

Parameters

elemGuid	[in] The element GUID to search for.
properties	[in] Specifies the properties to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of the 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 the given element.

Example

GSErrCode SetAllPropertyValuesToDefault (const API_Guid& elemGuid)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValues (elemGuid, definitions, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                properties[i].isDefault = true;
            }
            error = ACAPI_Element_SetProperties (elemGuid, properties);
        }
    }
 
    return error;
}

ACAPI_Element_SetPropertiesOfDefaultElem()

GSErrCode __ACENV_CALL ACAPI_Element_SetPropertiesOfDefaultElem	(	const API_ElemType &	type,
		const GS::Array< API_Property > &	properties
	)

Sets the specified properties for the given values on an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
properties	[in] Specifies the properties to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified or one of the property definitions' guid did not refer to a valid object.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of the 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 the given element.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode SetAllPropertyValuesToDefault (const API_ElemType& type)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValuesOfDefaultElem (type, definitions, properties);
        if (error == NoError) {
            for (UInt32 i = 0; i < properties.GetSize (); i++) {
                properties[i].isDefault = true;
            }
            error = ACAPI_Element_SetPropertiesOfDefaultElem (type, properties);
        }
    }
 
    return error;
}

ACAPI_Element_SetProperty()

GSErrCode __ACENV_CALL ACAPI_Element_SetProperty	(	const API_Guid &	elemGuid,
		const API_Property &	property
	)

Sets the specified property for the given values on an element.

Parameters

elemGuid	[in] The element GUID to search for.
property	[in] Specifies the property to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of the 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 the given element.

Example

GSErrCode SetFirstPropertyValueToDefault (const API_Guid& elemGuid)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError && definitions.GetSize () > 0) {
        API_Property property = {};
        error = ACAPI_Element_GetPropertyValue (elemGuid, definitions[0].guid, property);
        if (error == NoError) {
            property.isDefault = true;
            error = ACAPI_Element_SetProperty (elemGuid, property);
        }
    }
 
    return error;
}

ACAPI_Element_SetPropertyOfDefaultElem()

GSErrCode __ACENV_CALL ACAPI_Element_SetPropertyOfDefaultElem	(	const API_ElemType &	type,
		const API_Property &	property
	)

Sets the specified property to the given value on an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
property	[in] Specifies the property to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Incorrect type was specified or one of the property definitions' guid did not refer to a valid object.
• APIERR_NOACCESSRIGHT - The current user does not have the right to modify the properties of the 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 the given element.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode SetFirstPropertyValueToDefault (const API_ElemType& type)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError) {
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValuesOfDefaultElem (type, definitions, properties);
        if (error == NoError) {
            API_Property property = properties[0];
            property.isDefault = true;
 
            error = ACAPI_Element_SetPropertyOfDefaultElem (type, property);
        }
    }
 
    return error;
}

ACAPI_Notification_PropertyVisibilityChanged()

GSErrCode __ACENV_CALL ACAPI_Notification_PropertyVisibilityChanged

(

)

Sends out an APINotify_PropertyVisibilityChanged project event notification to the other add-ons to state that at least one property's visibility has changed.

Returns

• NoError - The function completed successfully.

ACAPI_Property_AddProperty()

GSErrCode __ACENV_CALL ACAPI_Property_AddProperty	(	API_PropertyDefinition &	definition,
		const GS::Array< API_Guid > &	elemGuids
	)

Makes a property definition available for all of given elements (it is created if it does not exist).

Parameters

definition	[in] The GUID of the definition (if already existing) or the data of the definition to create. [out] The GUID of the definition (if newly created) and the modified availability array.
elemGuids	[in] The array of elements, that the property should be available for.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The groupGuid of the parameter did not refer to a valid property group or one of the availabilities' guid did not refer to a valid structural type category value or one of elemGuids did not refer to a valid element.
• APIERR_NOACCESSRIGHT - Do not have the right to create or modify a property definition on a teamwork server.
• APIERR_NAMEALREADYUSED - The name of the definition is already used in the given property group.
• APIERR_BADPARS - The value of the definition is inconsistent, for example the default value has a different value type than the definition itself.
• APIERR_BADVALUE - One of enumerations did not have their value out of the allowed ones. This includes c++ enums (i.e. they were uninitialized or memsetted), and enumeration property values (the possibleEnumValues doesn't contain the default value)

Example

GSErrCode CreateExamplePropertyDefinitionForSelection (API_Guid groupGuid, const GS::Array<API_Guid>& selectedElements, API_PropertyDefinition& definition)
{
    definition.guid = APINULLGuid;
    definition.groupGuid = groupGuid;
    definition.name = "Property Definition";
    definition.description = "An example property definition.";
    definition.collectionType = API_PropertySingleCollectionType;
    definition.valueType = API_PropertyBooleanValueType;
    definition.defaultValue.singleVariant.variant.type = definition.valueType;
    definition.defaultValue.singleVariant.variant.boolValue = false;
 
    return ACAPI_Property_AddProperty (definition, selectedElements);
}

ACAPI_Property_ChangePropertyDefinition()

GSErrCode __ACENV_CALL ACAPI_Property_ChangePropertyDefinition

(

const API_PropertyDefinition &

definition

)

Changes an already existing property definition in the current plan (identified by its guid).

Parameters

definition

[in] The property definition to change.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The guid of the parameter did not refer to a valid property definition or the groupGuid of the parameter did not refer to a valid property group or one of the availabilities' guid did not refer to a valid structural type category value.
• APIERR_NOACCESSRIGHT - Do not have the right to modify a property definition on a teamwork server.
• APIERR_NAMEALREADYUSED - The new name of the definition is already used in the target property group.
• APIERR_BADPARS - Either the new value of the definition is inconsistent, for example the default value has a different value type than the definition itself, or the definitionType of the definition is not supported by the function.
• APIERR_BADVALUE - One of enumerations did not have their value out of the allowed ones. This includes c++ enums (i.e. they were uninitialized or memsetted), and enumeration property values (the possibleEnumValues doesn't contain the default value)

Example

GSErrCode RenameFirstPropertyDefinition ()
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Element_GetPropertyDefinitions (APINULLGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
    if (error == NoError && definitions.GetSize () > 0) {
       definitions[0].name = "Renamed Property Definition";
       error = ACAPI_Property_ChangePropertyDefinition (definitions[0]);
    }
 
    return error;
}

ACAPI_Property_ChangePropertyGroup()

GSErrCode __ACENV_CALL ACAPI_Property_ChangePropertyGroup

(

const API_PropertyGroup &

group

)

Changes an already existing property group in the current plan (identified by its guid).

Parameters

group

[in] The property group to change.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The guid of the parameter did not refer to a valid property group.
• APIERR_BADPARS - The groupType of the parameter is not supported by the function.
• APIERR_NOACCESSRIGHT - Do not have the right to modify a property group on a teamwork server.
• APIERR_NAMEALREADYUSED - The new name of the group is already used.

Example

GSErrCode RenameFirstPropertyGroup ()
{
    GS::Array<API_PropertyGroup> groups;
    GSErrCode error = ACAPI_Property_GetPropertyGroups (groups);
    if (error == NoError && groups.GetSize () > 0) {
       groups[0].name = "Renamed Property Group";
       groups[0].description = "Description is also modified";
       error = ACAPI_Property_ChangePropertyGroup (groups[0]);
    }
 
    return error;
}

ACAPI_Property_CheckPropertyExpressionString()

GSErrCode __ACENV_CALL ACAPI_Property_CheckPropertyExpressionString

(

GS::UniString *

expressionString

)

Checks if the given property expression is a syntactically valid one.

Parameters

expressionString

[in] The expression whose validity is to be decided.

Returns

• NoError - The given expression string is a syntactically valid one.
• APIERR_BADEXPRESSION - The given expression string is syntactically incorrect.
• APIERR_BADPARS - Some of the parameters are nullptr.

Remarks

This function is used to determine whether a property expression string is syntactically correct. It tries to parse the expression, and APIERR_BADEXPRESSION is returned when it fails because of some syntax error.

ACAPI_Property_CreatePropertyDefinition()

GSErrCode __ACENV_CALL ACAPI_Property_CreatePropertyDefinition

(

API_PropertyDefinition &

definition

)

Creates a property definition in the current plan.

Parameters

definition

[in/out] The property definition to create. Once the operation completed successfully the guid field is overwritten with the id of the newly created property definition.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The groupGuid of the parameter did not refer to a valid property group or one of the availabilities' guid did not refer to a valid structural type category value.
• APIERR_NOACCESSRIGHT - Do not have the right to create a property definition on a teamwork server.
• APIERR_NAMEALREADYUSED - The name of the definition is already used in the given property group.
• APIERR_BADPARS - Either the value of the definition is inconsistent, for example the default value has a different value type than the definition itself, or the definitionType of the parameter is not supported by the function.
• APIERR_BADVALUE - One of enumerations did not have their value out of the allowed ones. This includes c++ enums (i.e. they were uninitialized or memsetted), and enumeration property values (the possibleEnumValues doesn't contain the default value)

Example

GSErrCode CreateExamplePropertyDefinition (API_Guid groupGuid, API_PropertyDefinition& definition)
{
    definition.guid = APINULLGuid;
    definition.groupGuid = groupGuid;
    definition.name = "Property Definition";
    definition.description = "An example property definition.";
    definition.collectionType = API_PropertySingleCollectionType;
    definition.valueType = API_PropertyBooleanValueType;
    definition.definitionType = API_PropertyCustomDefinitionType;
    definition.defaultValue.singleVariant.variant.type = definition.valueType;
    definition.defaultValue.singleVariant.variant.boolValue = false;
 
    return ACAPI_Property_CreatePropertyDefinition (definition);
}

ACAPI_Property_CreatePropertyGroup()

GSErrCode __ACENV_CALL ACAPI_Property_CreatePropertyGroup

(

API_PropertyGroup &

group

)

Creates a property group in the current plan.

Parameters

group

[in/out] The property group to create. Once the operation completed successfully the guid field is overwritten with the id of the newly created property group.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The groupType of the parameter is not supported by the function.
• APIERR_NOACCESSRIGHT - Do not have the right to create a property group on a teamwork server.
• APIERR_NAMEALREADYUSED - The name of the group is already used.

Example

GSErrCode CreateExamplePropertyGroup (API_PropertyGroup& group)
{
    group.guid = APINULLGuid;
    group.name = "An example property group.";
    group.description = "This is an example property group.";
 
    return ACAPI_Property_CreatePropertyGroup (group);
}

ACAPI_Property_DeleteProperty()

GSErrCode __ACENV_CALL ACAPI_Property_DeleteProperty	(	const API_Guid &	definitionGuid,
		const GS::Array< API_Guid > &	elemGuids
	)

Makes a property definition unavailable for all of given elements.

Parameters

definitionGuid	[in] The GUID of the definition to remove from the elements.
elemGuids	[in] The array of elements, that the property should not be available for.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Do not have the right to modify a property definition on a teamwork server.
• APIERR_BADID - One of the elemGuids did not refer to a valid element.

Example

GSErrCode DeleteIntegerPropetiesOfSelection (GS::Array<API_Guid> selectedElements)
{
    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) {
            GSErrCode err = ACAPI_Property_DeleteProperty (definitions[i].guid, selectedElements));
            if (err != NoError) {
                return err;
            }
        }
    }
    return NoError;
}

ACAPI_Property_DeletePropertyDefinition()

GSErrCode __ACENV_CALL ACAPI_Property_DeletePropertyDefinition

(

const API_Guid &

propertyGuid

)

Deletes a property definition in the current plan.

Parameters

propertyGuid

[in] The identifier of the property definition to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The propertyGuid parameter did not refer to a valid property definition.
• APIERR_NOACCESSRIGHT - Do not have the right to delete a property definition on a teamwork server.

Example

GSErrCode DeleteAllPropertyDefinitions ()
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
    for (UInt32 i = 0; error == NoError && i < definitions.GetSize (); i++) {
        error = ACAPI_Property_DeletePropertyDefinition (definitions[i].guid);
    }
 
    return error;
}

ACAPI_Property_DeletePropertyGroup()

GSErrCode __ACENV_CALL ACAPI_Property_DeletePropertyGroup

(

const API_Guid &

groupGuid

)

Deletes a property group and all of the property definitions inside in the current plan.

Parameters

groupGuid

[in] The identifier of the property group to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The groupGuid parameter did not refer to a valid property group.
• APIERR_NOACCESSRIGHT - Do not have the right to delete a property group on a teamwork server.

Example

GSErrCode DeleteAllPropertyGroups ()
{
    GS::Array<API_PropertyGroup> groups;
    GSErrCode error = ACAPI_Property_GetPropertyGroups (groups);
    for (UInt32 i = 0; error == NoError && i < groups.GetSize (); i++) {
        error = ACAPI_Property_DeletePropertyGroup (groups[i].guid);
    }
 
    return error;
}

ACAPI_Property_GetPropertyDefinition()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyDefinition

(

API_PropertyDefinition &

definition

)

Retrieves one property definition identified by its guid.

Parameters

definition

[in/out] The guid field specifies the property definition to retrieve. Once the operation completed successfully this will hold the retrieved property definition.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The guid of the parameter did not refer to a valid property definition.

Example

GSErrCode GetPropertyDefinitionName (const API_Guid& guid, GS::UniString& name)
{
    API_PropertyDefinition definition;
    definition.guid = guid;
    GSErrCode error = ACAPI_Property_GetPropertyDefinition (definition);
 
    if (error == NoError)
        name = definition.name;
 
    return error;
}

ACAPI_Property_GetPropertyDefinitions()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyDefinitions	(	const API_Guid &	groupGuid,
		GS::Array< API_PropertyDefinition > &	definitions
	)

Retrieves all the property definitions from a given group.

Parameters

groupGuid	[out] The identifier of the group to search for or APINULLGuid if all property definitions should be retrieved.
definitions	[out] The retrieved property definitions.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The groupGuid parameter wasn't APINULLGuid and it did not refer to a valid property group.

Example

GSErrCode GetPropertyNames (GS::Array<GS::UniString>& names)
{
    GS::Array<API_PropertyDefinition> definitions;
    GSErrCode error = ACAPI_Property_GetPropertyDefinitions (APINULLGuid, definitions);
 
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            names.Push (definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Property_GetPropertyExprReferenceString()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyExprReferenceString	(	API_PropertyDefinition *	propertyDefinition,
		GS::UniString *	propertyReferenceString
	)

Returns the string that can be used in expressions to refer to a specific property.

Parameters

propertyDefinition	[in] The property definition to be refenced by the returned string.
propertyReferenceString	[out] String for storing the returned property reference string.

Returns

• NoError - The operation was successful.
• APIERR_BADPARS - Some of the parameters are nullptr.

ACAPI_Property_GetPropertyGroup()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyGroup

(

API_PropertyGroup &

group

)

Retrieves one property group identified by its guid.

Parameters

group

[in/out] The guid field specifies the property group to retrieve. Once the operation completed successfully this will hold the retrieved property group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The guid of the parameter did not refer to a valid property group.

Example

GSErrCode GetPropertyGroupName (const API_Guid& guid, GS::UniString& name)
{
    API_PropertyGroup group;
    group.guid = guid;
    GSErrCode error = ACAPI_Property_GetPropertyGroup (group);
 
    if (error == NoError)
        name = group.name;
 
    return error;
}

ACAPI_Property_GetPropertyGroups()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyGroups

(

GS::Array< API_PropertyGroup > &

groups

)

Retrieves all the property groups.

Parameters

groups

[out] The retrieved property groups.

Returns

• NoError - The function has completed with success.

Example

GSErrCode GetPropertyGroupNames (GS::Array<GS::UniString>& names)
{
    GS::Array<API_PropertyGroup> groups;
    GSErrCode error = ACAPI_Property_GetPropertyGroups (groups);
 
    if (error == NoError) {
        for (UInt32 i = 0; i < groups.GetSize (); i++) {
            names.Push (groups[i].name);
        }
    }
 
    return error;
}

ACAPI_Property_GetPropertyValueString()

GSErrCode __ACENV_CALL ACAPI_Property_GetPropertyValueString	(	const API_Property &	apiProperty,
		GS::UniString *	resultString
	)

Convert an API property value to display string.

Since

Archicad 25

Parameters

apiProperty	[in] An evaluated property with its value.
resultString	[out] The string representation of the given property value. The function can resolve enumeration values (which are stored by the keyVariant in the apiProperty), as well as convert measured numeric values based on the current Project Preferences.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect variant or param was specified.

ACAPI_Property_Import()

GSErrCode __ACENV_CALL ACAPI_Property_Import	(	const GS::UniString &	propertyXml,
		API_PropertyDefinitionNameConflictResolutionPolicy	conflictPolicy
	)

Imports a property xml.

Parameters

propertyXml	[in] The property xml to import.
conflictPolicy	[in] Specifies how to resolve name conflicts. API_PropertyDefinitionNameConflictResolutionPolicy Meaning API_AppendConflictingProperties Generate a new, unused name for the imported property API_ReplaceConflictingProperties Replace the definition in the plan with the imported one API_SkipConflictingProperties Keep the definition in the plan intact, and discard the imported one

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Invalid property XML.

ACAPI_Property_InstallPropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_Property_InstallPropertyObjectHandler	(	short	strResID,
		APIPropertyObjectCommandProc *	propertyCommandProc
	)

Installs the property handler function for the given menu item.

Parameters

strResID	[in] The string resource ID you install the property handler for.
propertyCommandProc	[in] The property command handler function.

Returns

• NoError - The function has completed with success.

Remarks

The string resource will appear in Archicad's dialogs. This function should be called from the Initialize function of the add-on, after registering the property handler with ACAPI_Property_RegisterPropertyObjectHandler.

Example

//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode __ACENV_CALL  Initialize (void)
{
    ACAPI_MenuItem_InstallMenuHandler (MenuResId, Callback_Check_AVA_OR_DIN_MenuItem);
    ACAPI_Property_InstallPropertyObjectHandler (PropertyResId, Callback_Property);
 
    return NoError;
}

ACAPI_Property_InstallPropertyVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_Property_InstallPropertyVisibilityHandler

(

APIPropertyVisibilityHandlerProc *

handlerProc

)

Installs the property visibility handler function.

Parameters

handlerProc

[in] The property visibility handler function.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the Initialize function of the add-on, after registering the property handler with ACAPI_Property_RegisterPropertyVisibilityHandler.

Example

//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode __ACENV_CALL  APIMenuCommandProc_Main   (const API_MenuParams *menuParams);
bool      __ACENV_CALL  PropertyVisibilityHandler (API_PropertyVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& propertyDefinitionGuid);
 
GSErrCode __ACENV_CALL  Initialize (void)
{
    GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, APIMenuCommandProc_Main);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_Property_InstallPropertyVisibilityHandler (PropertyVisibilityHandler);
    if (err != NoError) {
        return err;
    }
 
    ACAPI_KeepInMemory (true);
    return NoError;
}

ACAPI_Property_IsValidValue()

bool __ACENV_CALL ACAPI_Property_IsValidValue	(	const API_PropertyValue &	value,
		const API_PropertyDefinition &	definition
	)

Returns true if the value is acceptable for the given property definition.

Since

Archicad 25

Parameters

value	[in] The value to check.
definition	[in] The valueType, collectionType and possibleEnumValues of the definition will be used to check the validity of the value.

Returns

• true - The given value's variantStatus is API_VariantStatusNormal or API_VariantStatusUserUndefined and value's variant.type is the same as definition's valueType.

Example

GS::Array<API_PropertyDefinition> GetPropertiesOfElementForPropertyValue (const API_Guid& elemGuid, const API_PropertyValue& propertyValue)
{
    GS::Array<API_PropertyDefinition> definitions;
    ACAPI_Element_GetPropertyDefinitions (elemGuid, API_PropertyDefinitionFilter_UserDefined, definitions);
 
    GS::Array<API_PropertyDefinition> filteredDefinition;
    for (const API_PropertyDefinition& definition : definitions) {
        if (ACAPI_Property_IsValidValue (propertyValue, definition)
) {
            filteredDefinition.Push (definition);
        }
    }
    return filteredDefinition;
}

ACAPI_Property_ModifyPropertyValue()

GSErrCode __ACENV_CALL ACAPI_Property_ModifyPropertyValue	(	const API_Property &	property,
		const GS::Array< API_Guid > &	elemGuids
	)

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.

Parameters

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

Returns

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

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_Property_ModifyPropertyValue (property, filteredSelectedElements);
            if (err != NoError) {
                return err;
            }
        }
    }
    return NoError;
}

ACAPI_Property_RegisterPropertyObjectHandler()

GSErrCode __ACENV_CALL ACAPI_Property_RegisterPropertyObjectHandler

(

short

assignStrResID

)

Registers a property handler.

Parameters

assignStrResID

[in] The string resource ID, which will be used in Archicad's dialogs.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the RegisterInterface routine in your add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    ACAPI_MenuItem_RegisterMenu (MenuResId, MenuTextResId, MenuCode_Calculate, MenuFlag_Default);
    ACAPI_Property_RegisterPropertyObjectHandler (PropertyResId);
 
    return NoError;
}   // RegisterInterface

ACAPI_Property_RegisterPropertyVisibilityHandler()

GSErrCode __ACENV_CALL ACAPI_Property_RegisterPropertyVisibilityHandler

(

void

)

Tells Archicad that your add-on wants to modify property visibility.

Returns

• NoError - The function has completed with success.

Remarks

This function should be called from the RegisterInterface routine in your add-on.

Example

//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL  RegisterInterface (void)
{
    GSErrCode err = ACAPI_MenuItem_RegisterMenu (32500, 32600, MenuCode_UserDef, MenuFlag_Default);
    if (err != NoError) {
        return err;
    }
 
    err = ACAPI_Property_RegisterPropertyVisibilityHandler ();
    if (err != NoError) {
        return err;
    }
 
    return NoError;
}   // RegisterInterface

ACAPI_Property_SetPropertyValueFromString()

GSErrCode __ACENV_CALL ACAPI_Property_SetPropertyValueFromString	(	const GS::UniString &	propertyValueString,
		const API_PropertyConversionUtilsInterface &	conversionUtils,
		API_Property *	property
	)

Sets the value of a property value from a passed string.

Since

Archicad 25

Parameters

propertyValueString	[in] The string from which the new value will be generated.
conversionUtils	[in] The implementation of API_PropertyConversionUtilsInterface.
property	[in/out] The property whose value we want to set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The API_Property is nullptr, the property definition does not exist or the value creation from the string failed.
• APIERR_BADVALUE - The property definition is invalid.

Remarks

This function doesn't modify the database, only fills the API_Property structure with the appropriate values. In order to introduce the new values to the database the add-on has to call ACAPI_Element_SetProperty or ACAPI_Element_SetProperties.

Example

class PropertyConversionUtils : public API_PropertyConversionUtilsInterface {
private:
    const GS::UniString degreeSymbol    = " ";
    const GS::UniString minuteSymbol    = "'";
    const GS::UniString secondSymbol    = "\"";
    const GS::UniString gradientSymbol  = "G";
    const GS::UniString radianSymbol    = "R";
    const GS::UniString northSymbol     = "N";
    const GS::UniString southSymbol     = "S";
    const GS::UniString eastSymbol      = "E";
    const GS::UniString westSymbol      = "w";
 
public:
    virtual ~PropertyConversionUtils ();
 
    virtual const GS::UniString& GetDegreeSymbol1 () const { return degreeSymbol; }
    virtual const GS::UniString& GetDegreeSymbol2 () const { return degreeSymbol; }
    virtual const GS::UniString& GetMinuteSymbol () const { return minuteSymbol; }
    virtual const GS::UniString& GetSecondSymbol () const { return secondSymbol; }
 
    virtual const GS::UniString& GetGradientSymbol () const { return gradientSymbol; }
    virtual const GS::UniString& GetRadianSymbol () const { return radianSymbol; }
 
    virtual const GS::UniString& GetNorthSymbol () const { return northSymbol; }
    virtual const GS::UniString& GetSouthSymbol () const { return southSymbol; }
    virtual const GS::UniString& GetEastSymbol () const { return eastSymbol; }
    virtual const GS::UniString& GetWestSymbol () const { return westSymbol; }
 
    virtual GS::uchar_t                 GetDecimalDelimiterChar () const { return '.'; }
    virtual GS::Optional<GS::UniChar>   GetThousandSeparatorChar () const { return ' '; }
 
    virtual API_LengthTypeID    GetLengthType () const { return API_LengthTypeID::Meter; }
    virtual API_AreaTypeID      GetAreaType () const { return API_AreaTypeID::SquareMeter; }
    virtual API_VolumeTypeID    GetVolumeType () const { return API_VolumeTypeID::CubicMeter; }
    virtual API_AngleTypeID     GetAngleType () const { return API_AngleTypeID::DecimalDegree; }
};
 
GSErrCode SetPropertyValue ()
{
    API_Property property = CreateIntPropertyDefinition ();
    const PropertyConversionUtils conversionUtils;
    return ACAPI_Property_SetPropertyValueFromString (L("9632 m"),
                              conversionUtils,
                              &property);
}