API Help
EPLAN API / User Guide / API DataModel / EPLAN properties
In This Topic
    EPLAN properties
    In This Topic

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

     

    Property types

    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: 

    PropertyDefinition.PropertyType oPropType = oPage.Properties[Properties.Page.DESIGNATION_PLANT].Definition.Type;
    
    Dim oPropType As PropertyDefinition.PropertyType = oPage.Properties(Properties.Page.DESIGNATION_PLANT).Definition.Type
    

    Setting and getting property

    The following example shows, how to set a bool property: 

    oFunction.Properties[Properties.Function.FUNC_ARTICLE_SUPPRESSINPARTSLIST] = true;
    
    oFunction.Properties(Properties.Function.FUNC_ARTICLE_SUPPRESSINPARTSLIST) = PropertyValue.op_Implicit(True)
    
     
    

    The following example, shows, how to get a MultiLangString property (project description): 

     

    MultiLangString mlTest = oProject.Properties[Properties.Project.PROJ_INSTALLATIONNAME];
    
    Dim mlTest As MultiLangString = oProject.Properties(Properties.Project.PROJ_INSTALLATIONNAME).ToMultiLangString()
    

     

    As an alternative syntax, you can also write: 

    MultiLangString mlTest = oProject.Properties.PROJ_INSTALLATIONNAME;
    
    Dim mlTest As MultiLangString = oProject.Properties.PROJ_INSTALLATIONNAME.ToMultiLangString()
    

     

    Finally an example, which loops over all string properties of a project: 

     string strTmp = string.Empty;
     PropertyValue oPropValue;
     // iterate over all project's properties
     foreach (AnyPropertyId hPProp in Eplan.EplApi.DataModel.Properties.AllProjectPropIDs)
     {
         // check if exists
         if (!m_oProject.Properties[hPProp].IsEmpty)
         {
             if (m_oProject.Properties[hPProp].Definition.Type == PropertyDefinition.PropertyType.String)
             {
                 //read string property
                 oPropValue = m_oProject.Properties[hPProp];
                 strTmp = oPropValue.ToString();
             }
         }
     }
    
    Dim strTmp As String = String.Empty
    Dim oPropValue As PropertyValue
    ' iterate over all project's properties
    Dim hPProp As AnyPropertyId
    For Each hPProp In  Eplan.EplApi.DataModel.Properties.AllProjectPropIDs
       ' check if exists
       If Not m_oProject.Properties(hPProp).IsEmpty Then
          If m_oProject.Properties(hPProp).Definition.Type = PropertyDefinition.PropertyType.String Then
             'read string property
             oPropValue = m_oProject.Properties(hPProp)
             strTmp = oPropValue.ToString()
          End If
       End If
    Next hPProp
    

    Conversion property value to another types

    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

    Indexed properties

    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: 

    strConnDes1 = oFunction.Properties[Properties.Function.FUNC_CONNECTIONDESIGNATION, 1].ToString();
    
    strConnDes1 = oFunction.Properties(Properties.Function.FUNC_CONNECTIONDESIGNATION, 1).ToString()
    

     

    Alternatively: 

    strConnDes1 = oFunction.Properties.FUNC_CONNECTIONDESIGNATION[1].ToString();
    
    strConnDes1 = oFunction.FUNC_CONNECTIONDESIGNATION(1).ToString()
    
     
    
     
    

    User-defined properties

    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 

     

    Accessing default user-defined properties

    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();
    

     

    See also "User-Defined Properties" chapter of EPLAN Help