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	APIPropertyObjectCommandProc(API_PropertyObjectParams *propertyParams)
	Callback function to handle the different property assignments.
typedef bool	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_PropertyGroupType { API_PropertyStaticBuiltInGroupType , API_PropertyDynamicBuiltInGroupType , API_PropertyCustomGroupType }
	Property group types. More...
enum	API_PropertyDefinitionType { API_PropertyStaticBuiltInDefinitionType , API_PropertyDynamicBuiltInDefinitionType , API_PropertyCustomDefinitionType }
	Property definition types. More...
enum	API_PropertyCollectionType {   API_PropertyUndefinedCollectionType , API_PropertySingleCollectionType , API_PropertyListCollectionType , API_PropertySingleChoiceEnumerationCollectionType ,   API_PropertyMultipleChoiceEnumerationCollectionType }
	Property collection types. More...
enum	API_PropertyMeasureType {   API_PropertyUndefinedMeasureType , API_PropertyDefaultMeasureType , API_PropertyLengthMeasureType , API_PropertyAreaMeasureType ,   API_PropertyVolumeMeasureType , API_PropertyAngleMeasureType }
	Property measure types. More...
enum	API_VariantType {   API_PropertyUndefinedValueType , API_PropertyIntegerValueType , API_PropertyRealValueType , API_PropertyStringValueType ,   API_PropertyBooleanValueType , API_PropertyGuidValueType }
	Variant value types. More...
enum	API_VariantStatus { API_VariantStatusNull , API_VariantStatusUserUndefined , API_VariantStatusNormal }
	Describes the status of a variant value. More...
enum	API_PropertyDefinitionFilter { API_PropertyDefinitionFilter_UserDefined , API_PropertyDefinitionFilter_BuiltIn , API_PropertyDefinitionFilter_All }
	Property definition filters. More...
enum	API_PropertyValueStatus { API_Property_NotAvailable , API_Property_NotEvaluated , API_Property_HasValue }
	Property value status. More...

Functions
GSErrCode	ACAPI_Property_CheckPropertyExpressionString (GS::UniString *expressionString)
	Checks if the given property expression is a syntactically valid one.
GSErrCode	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	ACAPI_Property_RegisterPropertyObjectHandler (short assignStrResID)
	Registers a property handler.
GSErrCode	ACAPI_Property_RegisterPropertyVisibilityHandler (void)
	Tells Archicad that your add-on wants to modify property visibility.
GSErrCode	ACAPI_Property_InstallPropertyObjectHandler (short strResID, APIPropertyObjectCommandProc *propertyCommandProc)
	Installs the property handler function for the given menu item.
GSErrCode	ACAPI_Property_InstallPropertyVisibilityHandler (APIPropertyVisibilityHandlerProc *handlerProc)
	Installs the property visibility handler function.
GSErrCode	ACAPI_Element_GetPropertyObjects (const API_Elem_Head *elemHead, API_PropertyObjectRefType ***propRefs, Int32 *nProp)
	Returns property objects of the element.
GSErrCode	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	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	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	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	ACAPI_Element_SetProperty (const API_Guid &elemGuid, const API_Property &property)
	Sets the specified property for the given values on an element.
GSErrCode	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	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	ACAPI_Element_GetPropertyValueOfDefaultElem (const API_ElemType &type, const API_Guid &propertyDefinitionGuid, API_Property &property)
	Retrieves the value of the specified property definition.
GSErrCode	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	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	ACAPI_Element_SetPropertyOfDefaultElem (const API_ElemType &type, const API_Property &property)
	Sets the specified property to the given value on an element default.
GSErrCode	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	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	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	ACAPI_Element_IsPropertyDefinitionAvailable (const API_Guid &elemGuid, const API_Guid &propertyGuid)
	Tells whether a property definition is available for an element.
bool	ACAPI_Element_IsPropertyDefinitionAvailableDefault (const API_ElemType &type, const API_Guid &propertyGuid)
	Tells whether a property definition is available for an element default.
bool	ACAPI_Element_IsPropertyDefinitionVisible (const API_Guid &elemGuid, const API_Guid &propertyGuid)
	Tells whether a property definition is visible for an element.
bool	ACAPI_Element_IsPropertyDefinitionVisibleDefault (const API_ElemType &type, const API_Guid &propertyGuid)
	Tells whether a property definition is visible for an element default.
GSErrCode	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	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	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	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	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	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	ACAPI_ActivatePropertyObjectHandler (short strResID, bool active)
	Activates or deactivates an add-on's property handler.
GSErrCode	ACAPI_Property_GetPropertyGroups (GS::Array< API_PropertyGroup > &groups)
	Retrieves all the property groups.
GSErrCode	ACAPI_Property_GetPropertyDefinitions (const API_Guid &groupGuid, GS::Array< API_PropertyDefinition > &definitions)
	Retrieves all the property definitions from a given group.
GSErrCode	ACAPI_Property_GetPropertyGroup (API_PropertyGroup &group)
	Retrieves one property group identified by its guid.
GSErrCode	ACAPI_Property_GetPropertyDefinition (API_PropertyDefinition &definition)
	Retrieves one property definition identified by its guid.
GSErrCode	ACAPI_Property_CreatePropertyGroup (API_PropertyGroup &group)
	Creates a property group in the current plan.
GSErrCode	ACAPI_Property_CreatePropertyDefinition (API_PropertyDefinition &definition)
	Creates a property definition in the current plan.
GSErrCode	ACAPI_Property_ChangePropertyGroup (const API_PropertyGroup &group)
	Changes an already existing property group in the current plan (identified by its guid).
GSErrCode	ACAPI_Property_ChangePropertyDefinition (const API_PropertyDefinition &definition)
	Changes an already existing property definition in the current plan (identified by its guid).
bool	ACAPI_Property_IsValidValue (const API_PropertyValue &value, const API_PropertyDefinition &definition)
	Returns true if the value is acceptable for the given property definition.
GSErrCode	ACAPI_Property_DeletePropertyGroup (const API_Guid &groupGuid)
	Deletes a property group and all of the property definitions inside in the current plan.
GSErrCode	ACAPI_Property_DeletePropertyDefinition (const API_Guid &propertyGuid)
	Deletes a property definition in the current plan.
GSErrCode	ACAPI_Property_Import (const GS::UniString &propertyXml, API_PropertyDefinitionNameConflictResolutionPolicy conflictPolicy)
	Imports a property xml.
GSErrCode	ACAPI_Property_GetPropertyValueString (const API_Property &apiProperty, GS::UniString *resultString)
	Convert an API property value to display string.
GSErrCode	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.
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetDegreeSymbol1 () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetDegreeSymbol2 () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetMinuteSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetSecondSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetGradientSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetRadianSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetNorthSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetSouthSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetEastSymbol () const =0
virtual const GS::UniString &	API_PropertyConversionUtilsInterface::GetWestSymbol () const =0
virtual GS::uchar_t	API_PropertyConversionUtilsInterface::GetDecimalDelimiterChar () const =0
virtual GS::Optional< GS::UniChar >	API_PropertyConversionUtilsInterface::GetThousandSeparatorChar () const =0
virtual API_LengthTypeID	API_PropertyConversionUtilsInterface::GetLengthType () const =0
virtual API_AreaTypeID	API_PropertyConversionUtilsInterface::GetAreaType () const =0
virtual API_VolumeTypeID	API_PropertyConversionUtilsInterface::GetVolumeType () const =0
virtual API_AngleTypeID	API_PropertyConversionUtilsInterface::GetAngleType () const =0

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 efficiently manipulate properties for a list of elements.

• ACAPI_Property_ModifyPropertyValue

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

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

• ACAPI_Attribute_ModifyPropertyValue

Typedef Documentation

APIPropertyObjectCommandProc

typedef GSErrCode 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 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.

Enumeration Type Documentation

API_PropertyCollectionType

enum API_PropertyCollectionType

Property collection types.

Remarks

Defines different types of property collections.

Enumerator
API_PropertyUndefinedCollectionType	Represents an undefined collection type.
API_PropertySingleCollectionType	Represents a single collection type.
API_PropertyListCollectionType	Represents a list collection type.
API_PropertySingleChoiceEnumerationCollectionType	Represents a single choice enumeration collection type.
API_PropertyMultipleChoiceEnumerationCollectionType	Represents a multiple choice enumeration collection type.

API_PropertyDefinitionFilter

enum API_PropertyDefinitionFilter

Property definition filters.

Remarks

Defines different filters for property definitions.

Enumerator
API_PropertyDefinitionFilter_UserDefined	Represents a user-defined property definition filter.
API_PropertyDefinitionFilter_BuiltIn	Represents a built-in property definition filter.
API_PropertyDefinitionFilter_All	Represents a filter for all property definitions.

API_PropertyDefinitionType

enum API_PropertyDefinitionType

Property definition types.

Remarks

Defines different types of property definitions.

Enumerator
API_PropertyStaticBuiltInDefinitionType	It is a built-in property (the definition itself is read only). The set of static built-in properties do not change.
API_PropertyDynamicBuiltInDefinitionType	It is a built-in property (the definition itself is read only). The set of dynamic built-in properties may change as a result of Archicad operations.
API_PropertyCustomDefinitionType	It is a user-defined property definition (can be modified).

API_PropertyGroupType

enum API_PropertyGroupType

Property group types.

Remarks

Defines different types of property groups.

Enumerator
API_PropertyStaticBuiltInGroupType	Represents a static built-in group type.
API_PropertyDynamicBuiltInGroupType	Represents a dynamic built-in group type.
API_PropertyCustomGroupType	Represents a custom group type.

API_PropertyMeasureType

enum API_PropertyMeasureType

Property measure types.

Remarks

Defines different types of property measures.

Enumerator
API_PropertyUndefinedMeasureType	Represents an undefined measure type.
API_PropertyDefaultMeasureType	Represents a default measure type.
API_PropertyLengthMeasureType	Represents a length measure type.
API_PropertyAreaMeasureType	Represents an area measure type.
API_PropertyVolumeMeasureType	Represents a volume measure type.
API_PropertyAngleMeasureType	Represents an angle measure type.

API_PropertyValueStatus

enum API_PropertyValueStatus

Property value status.

Remarks

Defines the status of a property value.

Enumerator
API_Property_NotAvailable	Indicates that the property is not available.
API_Property_NotEvaluated	Indicates that the property has not been evaluated.
API_Property_HasValue	Indicates that the property has a value.

API_VariantStatus

enum API_VariantStatus

Describes the status of a variant value.

Enumerator
API_VariantStatusNull	Indicates that the variant is invalid in some way, e.g., it is a result of an unsuccesful operation.
API_VariantStatusUserUndefined	The variant is explicitly set to undefined by the user, but it is still valid.
API_VariantStatusNormal	The variant has a usable and valid value.

API_VariantType

enum API_VariantType

Variant value types.

Remarks

Defines different types of variant values.

Enumerator
API_PropertyUndefinedValueType	Represents an undefined value type.
API_PropertyIntegerValueType	Represents an integer value type.
API_PropertyRealValueType	Represents a real number (double) value type.
API_PropertyStringValueType	Represents a string value type.
API_PropertyBooleanValueType	Represents a boolean value type.
API_PropertyGuidValueType	Represents a GUID value type.

Function Documentation

ACAPI_ActivatePropertyObjectHandler()

GSErrCode 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 {};
    GSFlags         flags;
 
    mir.menuResID = menuResID;
    mir.itemIndex = 1;
    ACAPI_MenuItem_GetMenuItemFlags (&mir, &flags);
    if (checkedAssignProperty)
        flags = flags | API_MenuItemChecked;
    else
        flags = flags & !API_MenuItemChecked;
 
    ACAPI_MenuItem_SetMenuItemFlags (&mir, &flags);
}

ACAPI_Element_GetPropertyDefinitions() [1/2]

GSErrCode 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 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_BuiltIn, 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 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, API_PropertyDefinitionFilter_All, definitions);
    if (error == NoError) {
        for (UInt32 i = 0; i < definitions.GetSize (); i++) {
            names.Push(definitions[i].name);
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyObjects()

GSErrCode 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;
 
    elemHead.guid = guid;
 
    err = ACAPI_Element_GetPropertyObjects (&elemHead, &propRefs, &nProp);
    if (err == NoError) {
        for (i = 0; i < nProp; i++) {
            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 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 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.value;
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValueOfDefaultElem()

GSErrCode 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.value;
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValues() [1/2]

GSErrCode 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 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.basicValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesByGuid() [1/2]

GSErrCode 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 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 (const API_PropertyDefinition& definition : definitions) {
            if (ACAPI_Element_IsPropertyDefinitionVisible (elemGuid, definition.guid)) {
                propertyDefinitionList.Push (definition.guid);
            }
        }
        GS::Array<API_Property> properties;
        error = ACAPI_Element_GetPropertyValuesByGuid (elemGuid, propertyDefinitionList, properties);
        if (error == NoError) {
            for (const API_Property& property : properties) {
                if (property.isDefault) {
                    values.Push (property.definition.defaultValue.basicValue);
                } else {
                    values.Push (property.value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesOfDefaultElem()

GSErrCode 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.basicValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_GetPropertyValuesOfDefaultElemByGuid()

GSErrCode 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_GetPropertyDefinitionsOfDefaultElem (type, API_PropertyDefinitionFilter_UserDefined, 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.basicValue);
                } else {
                    values.Push (properties[i].value);
                }
            }
        }
    }
 
    return error;
}

ACAPI_Element_IsPropertyDefinitionAvailable()

bool 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 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 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 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 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 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 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 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 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 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 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_ChangePropertyDefinition()

GSErrCode 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 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 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 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.basicValue.singleVariant.variant.type = definition.valueType;
    definition.defaultValue.basicValue.singleVariant.variant.boolValue = false;
 
    return ACAPI_Property_CreatePropertyDefinition (definition);
}

ACAPI_Property_CreatePropertyGroup()

GSErrCode 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_DeletePropertyDefinition()

GSErrCode 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 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 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 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 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 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 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 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 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 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 Initialize (void)
{
    ACAPI_MenuItem_InstallMenuHandler (32000, Callback_Check_AVA_OR_DIN_MenuItem);
    ACAPI_Property_InstallPropertyObjectHandler (32500, Callback_Property);
 
    return NoError;
}

ACAPI_Property_InstallPropertyVisibilityHandler()

GSErrCode 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 APIMenuCommandProc_Main   (const API_MenuParams *menuParams);
bool PropertyVisibilityHandler (API_PropertyVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& propertyDefinitionGuid);
 
GSErrCode 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 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 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)
{
    GSErrCode 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.guid)) {
                    filteredSelectedElements.Push (selectedElements[i]);
                }
            }
 
            err = ACAPI_Property_ModifyPropertyValue (property, filteredSelectedElements);
            if (err != NoError) {
                return err;
            }
        }
    }
    return NoError;
}

ACAPI_Property_RegisterPropertyObjectHandler()

GSErrCode 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 RegisterInterface (void)
{
    ACAPI_MenuItem_RegisterMenu (MenuResId, MenuTextResId, MenuCode_Calculate, MenuFlag_Default);
    ACAPI_Property_RegisterPropertyObjectHandler (PropertyResId);
 
    return NoError;
}

ACAPI_Property_RegisterPropertyVisibilityHandler()

GSErrCode 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 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;
}

ACAPI_Property_SetPropertyValueFromString()

GSErrCode 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; }
};
 
PropertyConversionUtils::~PropertyConversionUtils () {}
 
GSErrCode SetPropertyValue ()
{
    API_Property property = CreateIntPropertyDefinition ();
    const PropertyConversionUtils conversionUtils;
    return ACAPI_Property_SetPropertyValueFromString (L("9632 m"),
                              conversionUtils,
                              &property);
}

GetAngleType()

virtual API_AngleTypeID API_PropertyConversionUtilsInterface::GetAngleType ( ) const

pure virtual

Returns

Returns the value for angle unit preferences.

GetAreaType()

virtual API_AreaTypeID API_PropertyConversionUtilsInterface::GetAreaType ( ) const

pure virtual

Returns

Returns the value for area unit preferences.

GetDecimalDelimiterChar()

virtual GS::uchar_t API_PropertyConversionUtilsInterface::GetDecimalDelimiterChar ( ) const

pure virtual

Returns

Returns the character of the decimal delimiter.

GetDegreeSymbol1()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetDegreeSymbol1 ( ) const

pure virtual

Returns

Returns the degree symbol.

GetDegreeSymbol2()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetDegreeSymbol2 ( ) const

pure virtual

Returns

Returns the degree symbol.

GetEastSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetEastSymbol ( ) const

pure virtual

Returns

Returns the east symbol.

GetGradientSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetGradientSymbol ( ) const

pure virtual

Returns

Returns the gradient symbol.

GetLengthType()

virtual API_LengthTypeID API_PropertyConversionUtilsInterface::GetLengthType ( ) const

pure virtual

Returns

Returns the value for length unit preferences.

GetMinuteSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetMinuteSymbol ( ) const

pure virtual

Returns

Returns the minute symbol.

GetNorthSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetNorthSymbol ( ) const

pure virtual

Returns

Returns the north symbol.

GetRadianSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetRadianSymbol ( ) const

pure virtual

Returns

Returns the radian symbol.

GetSecondSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetSecondSymbol ( ) const

pure virtual

Returns

Returns the second symbol.

GetSouthSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetSouthSymbol ( ) const

pure virtual

Returns

Returns the south symbol.

GetThousandSeparatorChar()

virtual GS::Optional< GS::UniChar > API_PropertyConversionUtilsInterface::GetThousandSeparatorChar ( ) const

pure virtual

Returns

Returns the character of the thousands separator.

GetVolumeType()

virtual API_VolumeTypeID API_PropertyConversionUtilsInterface::GetVolumeType ( ) const

pure virtual

Returns

Returns the value for volume unit preferences.

GetWestSymbol()

virtual const GS::UniString & API_PropertyConversionUtilsInterface::GetWestSymbol ( ) const

pure virtual

Returns

Returns the west symbol.