EPLAN API allows accessing object properties, i.e. characteristics which are visible in GUI in "Properties" dialog.
This is possible through Properties property which is defined for almost all DataModel objects.
The list of all available properties for a particular object, you can find in the properties of the Properties Class (for example Properties::AllMDSymbolLibraryPropIDs).
EPLAN properties are typed. The property values can have one of the following types:
With help of the PropertyDefinition.PropertyType, you can determine the type of a property:
PropertyDefinition.PropertyType | Corresponding .NET Framework type |
---|---|
Point | |
MultilangString | |
Variable | System.String |
String | System.String |
Time | System.DateTime |
Bool | System.Boolean |
Double | System.Double |
Coord | System.Double |
Long | System.Int64 |
The following example gets the type of a page property:
The following example shows, how to set a bool property:
The following example, shows, how to get a MultiLangString property (project description):
As an alternative syntax, you can also write:
Finally an example, which loops over all string properties of a project:
It is possible to get a property as a value of .NET Framework type or Eplan API type (for example Eplan.EplApi.Base.MultiLangString). It can be done explicitly by PropertyValue.To<type>() for example :
C# |
Copy Code
|
---|---|
string strStringValue = oFunction.Properties.FUNC_CODE.ToString();
|
or implicitly :
C# |
Copy Code
|
---|---|
int nValue = oFunction.Properties.FUNC_CRAFT;
|
It is not allowed to convert property value to non-matching type, for example MultiLangString to int. In such cases there will be a runtime warning generated (as Eplan system message) or an exception thrown :
C# |
Copy Code
|
---|---|
string strValue = oArticle.Properties.ARTICLE_DEPTH.ToString(); //will generate a system warning double dValue = oArticle.Properties.ARTICLE_DEPTH.ToDouble(); //ok string strValue2 = oArticle.Properties.ARTICLE_DEPTH.ToDouble().ToString("0.00", CultureInfo.InvariantCulture); //also ok |
Here is a table that shows which conversions are allowed :
|
Eplan.EplApi.Base.Point PropertyValue.ToPointD() |
Eplan.EplApi.Base.MultiLangString PropertyValue.ToMultiLangString() |
System.String PropertyValue.ToString() |
System.DateTime PropertyValue.ToTime() |
bool PropertyValue.ToBool() |
double PropertyValue.ToDouble() |
long PropertyValue.ToInt() |
---|---|---|---|---|---|---|---|
PropertyType.Point | ✓ | ||||||
PropertyType.MultilangString | ✓ | ||||||
PropertyType.Variable | ✓ | ||||||
PropertyType.String | ✓ | ||||||
PropertyType.Time | ✓ | ||||||
PropertyType.Bool | ✓ | ||||||
PropertyType.Double | ✓ | ||||||
PropertyType.Coord | ✓ | ||||||
PropertyType.Long |
✓ | ✓ |
Properties can have more than one value. In this case, we call it an indexed property. The index is passed after the property designation. The example gets index 1 of the function property FUNC_CONNECTIONDESIGNATION:
Alternatively:
EPLAN API supports also user-defined properties that were introduced in EPLAN 2.4
Following enhancements were added due to it :
- access to properties by case-sensitive string identifiers :
C# |
Copy Code
|
---|---|
//setting user-defined property oProject.Properties["EPLAN.Project.UserSupplementaryField1"] = "test1"; //getting user-defined property string strValue = oProject.Properties["EPLAN.Project.UserSupplementaryField1"]; |
- UserDefinedPropertyDefinition class extending PropertyDefinition. The class allows creating custom property definitions or accessing information from existing ones:
C# |
Copy Code
|
---|---|
//create new property definition : UserDefinedPropertyDefinition oUDPDProject = UserDefinedPropertyDefinition.Create(oCurrentProject, "API.Property.Project", UserDefinedPropertyDefinition.Enums.ClientType.Project); oCurrentProject.Properties["API.Property.Project"] = "something"; var oCategory = oProject.Properties["EPLAN.Project.UserSupplementaryField1"].Category; //gets category information MultiLangString strDisplayedName = oProject.Properties["EPLAN.Project.UserSupplementaryField1"].DisplayedName; //gets name that is displayed in GUI properties window |
- import/export property definitions (ExportPropertyDefinitions, ImportPropertyDefinitions from PrePlanningService class)
- new AnyPropertyId constructor allowing creating ID of user defined property:
C# |
Copy Code
|
---|---|
public AnyPropertyId( ref Eplan::EplApi::DataModel::Project pProject, ref System::String strUserDefiniedPropertyIdentName ); |
- AnyPropertyId.AsString propety to get identifying name from AnyPropertyId which represents user-defined property
- actions that expects id of a property were extend to support also identifying names. Please go to API Reference for details
Some user-defined properties are created by default, for example "EPLAN.Project.UserSupplementaryField1"
They have the same internal ids as old *_CUSTOM_SUPPLEMENTARYFIELD* properties (like "PROJ_CUSTOM_SUPPLEMENTARYFIELD01", etc).
Using old identifiers is still possible for compatibility reasons, however generates warnings and will be removed in future.
So please replace them with new IDs to unique problems in forthcoming EPLAN versions:
C# |
Copy Code
|
---|---|
MultiLangString oMLS = oProject.Properties.PROJ_CUSTOM_SUPPLEMENTARYFIELD01; //old code, generates warning MultiLangString oMLS = oProject.Properties["EPLAN.Project.UserSupplementaryField1"]; //new code m_oTestProject.Properties.FUNC_ARTICLE_CUSTOM_SUPPLEMENTARYFIELD01[1] = strTestValue; //old code, generates warning: ArticleReference oArticleReference = oProject.ArticleReferences[0]; //new code oArticleReference.Properties["EPLAN.PartRef.UserSupplementaryField1"] = strTestValue; oArticleReference.StoreToObject(); |
In case of an ArticleReference object, when accessing user-defined property by a parent an ArticleReference, there is necessary to add 'EPLAN.ArticleRef.' prefix to its identifying name. Also there must by index provided which is position of an ArticleReference at a parent object.
C# |
Copy Code
|
---|---|
var propertyValue1 = oArticleReference.Properties["UserProperty.1"].ToString(); //accessing user-defined property from ArticleReference var propertyValue2 = oArticleReference.Parent.Properties["EPLAN.ArticleRef.UserProperty.1"][1].ToString(); //accessing user-defined property from a parent of the ArticleReference |