API Help
EPLAN API / User Guide / API DataModel / Navigating the project data
In This Topic
    Navigating the project data
    In This Topic

    There are two distinct methods of navigating through the EPLAN project. The most common is to use the navigation properties which you can find on each data model object. In addition to that, there is the DMObjectsFinder Class. By its methods, you can retrieve filtered lists (arrays) of certain objects in a project. 

     

    Navigating through properties

    Regardless of the underlying implementation of EPLAN, the entire data model can be seen as a graph, with one to many and many to many relationships between the various object types in the graph. For example, a project has a one-to-many relationship with its pages. These relationships can be thought of as if they were simple basic arrays. Each of the objects of the EPLAN data model have a set of properties, which return such arrays of dependant objects, as you can see in the topic "Data model overview". 

    One of the most common requirements of a program is to loop through all of the objects in an array performing some function or other on each element. As an example, the class Eplan.EplApi.DataModel.Page has the following navigation properties, with each of which you can loop over a different collection of objects:

     

    There are also navigational properties with a one-to-one relationship, like Page.Project. 

     

    The following code snippet shows, how to loop over the Functions on a page and get the name of the Function: 

    // get an array with all functions on the page
    Function[] arrFuncs = oPage.Functions;
    // loop over the functions and get their names
    foreach(Function oF in arrFuncs)
    {
        string sName = oF.Name;
        // Do something with the Name
    }
    
    ' get an array with all functions on the page
    Dim arrFuncs As Function() = oPage.Functions
    ' loop over the functions and get their names
    Dim oF As Function
    For Each oF In  arrFuncs
       Dim sName As String = oF.Name
       ' Do something with the Name
    Next
    
     
    

     

    You even can filter these lists before getting them. The following example sets a filter to get only the functions, which have the function category PLUG. 

    //set filter category to PLUG
    oPage.Filter.resetFilter();
    oPage.Filter.Category = Function.Enums.Category.PLUG;
    //get all functions filtered by category=PLUG
    Function[] arrFuncs = oPage.Functions;
    foreach(Function oF in arrFuncs)
    {
        string sPlugName = oF.Name;
        // Do something with the Name
    }
    
    'set filter category to PLUG
    oPage.Filter.resetFilter()
    oPage.Filter.Category = Function.Enums.Category.PLUG
    'get all functions filtered by category=PLUG
    Dim arrFuncs As Function() = oPage.Functions
    Dim oF As Function
    For Each oF In  arrFuncs
       Dim sPlugName As String = oF.Name
       ' Do something with the Name
    Next
    

     

    Please mind, that using navigation properties in order to set properties of an object in a nested way (e.g. oRectangle.Pen.ColorId = 5 ) will not work. In the example you need to first get the Pen object from the rectangle and then change the color id and afterwards set the changed Pen object back to the Rectangle class. 

     

     DMObjectsFinder                    

     

    The DMObjectsFinder object is always initialized with a project. Starting with the project, it can get nearly any list of objects of a given type. Before getting the lists, they can be filtered by different means like a distinct set of properties. The following example gets all functions with a given device tag (name): 

     

    string strFuncName = "=AP+PT1-X4";
    // initialize the DMObjectsFinder with a project
    DMObjectsFinder oFinder = new DMObjectsFinder(m_oProject);
    FunctionsFilter oFunctionsFilter = new FunctionsFilter();
    oFunctionsFilter.ExactNameMatching = true;
    oFunctionsFilter.Name = strFuncName;
    //get function with given name from project
    Function[] arrFuncs = oFinder.GetFunctions(oFunctionsFilter);
    
    foreach(Function oF in arrFuncs)
    {
        Console.Out.WriteLine("Function name: '{0}'", oF.Name);
    }
    
    Dim strFuncName As String = "=AP+PT1-X4"
    ' initialize the DMObjectsFinder with a project
    Dim oFinder As New DMObjectsFinder(m_oProject)
    Dim oFunctionsFilter As New FunctionsFilter()
    oFunctionsFilter.ExactNameMatching = True
    oFunctionsFilter.Name = strFuncName
    'get function with given name from project
    Dim arrFuncs As Function() = oFinder.GetFunctions(oFunctionsFilter)
    
    Dim oF As Function
    For Each oF In  arrFuncs
       Console.Out.WriteLine("Function name: '{0}'", oF.Name)
    Next oF
    
     
    

    Search class

     

    The class Eplan.EplApi.HEServices.Search offers another way for finding objects in a project. The class corresponds to the dialogs Find>Find... and Find>Show Results... in the GUI of EPLAN. As in this dialogs, you have two result lists to store your search results. 

    Using this class you can search for any string in a specified range of objects. The following example demonstrates the usage of the Search class. 

    Search oSearch = new Search();
    // Set all needed settings
    oSearch[Search.Settings.CaseSensitive] = false;
    oSearch[Search.Settings.WholeTexts] = false;
    oSearch[Search.Settings.DeviceTag] = true;
    oSearch[Search.Settings.AllProperties] = false;
    oSearch[Search.Settings.Texts] = false;
    oSearch[Search.Settings.PageData] = false;
    oSearch[Search.Settings.ProjectData] = false;
    oSearch[Search.Settings.GraphicPages] = false;
    oSearch[Search.Settings.EvalutionPages] = false;
    oSearch[Search.Settings.NotPlaced] = false;
    oSearch.SearchDatabaseNr = 0;
    oSearch.ClearSearchDB(oProject, 0);
    if (oPage != null)
    {
        //either search in a page
        oSearch.Page(oPage, Name);
    }
    else
    {
        // or search through the complete project
        oSearch.Project(oProject, Name);
    }
    StorableObject[] oResults = oSearch.GetAllSearchDBEntries(oProject, 0);
    
    Dim oSearch As Search = New Search
    oSearch.SearchDatabaseNr = 0
    oSearch.ClearSearchDB(oProject, 0)
    oSearch(Search.Settings.AllProperties) = True
    oSearch(Search.Settings.CaseSensitive) = False
    oSearch(Search.Settings.DeviceTag) = True
    oSearch(Search.Settings.LogicPages) = True
    oSearch(Search.Settings.GraphicPages) = False
    oSearch(Search.Settings.EvalutionPages) = False
    oSearch(Search.Settings.NotPlaced) = False
    oSearch(Search.Settings.WholeTexts) = False
    oSearch(Search.Settings.PageData) = True
    oSearch(Search.Settings.ProjectData) = True
    oSearch.Project(oProject, txtSearch.Text)
    Dim oFoundObjects As StorableObject() = oSearch.GetAllSearchDBEntries(oProject, 0)