API Help
EPLAN API / User Guide / API Electrotechnical services / Messages
In This Topic
    Messages
    In This Topic

    As API developer, you can add new electrotechnical messages to EPLAN and to write them to the message management. 

    In order to create a new message, add a class to your project, which implements the interface IMessage. 

     

    The IEplMessage interface declares 3 functions:

    1. The parameters of the function OnRegister() define the properties of the message and how it is registered in EPLAN.
    2. The function GetMessageText() returns -- on request of EPLAN -- the message text, which is displayed in dialogs.
    3. The function DoHelp() is called by the system, if EPLAN request help about the message.
    public class Message: Eplan.EplApi.EServices.IMessage
    {
        public void OnRegister( ref IMessage.Region eRegionId, ref int iMessageId,
          ref IMessage.Classification eClassification, ref int iOrdinal)
        {
            eRegionId = IMessage.Region.Externals;
            iMessageId = 25;
            eClassification = IMessage.Classification.Error; iOrdinal = 20;
            return;
        }
        public System.String GetMessageText()
        {
            // TODO: Provide text from resource in active GUI language
            return "Message text for %1!s! from Eplan.EplAddIn.Demo.Messages";
        }
        public void DoHelp()
        {
            new Decider().Decide(EnumDecisionType.eOkDecision, "DoHelp was called!", "Eplan.EplAddIn.Demo.Messages", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK);
            // TODO: activate help for this message
        }
    }
    
    Public Class Message
       Implements Eplan.EplApi.EServices.IMessage
       Public Sub OnRegister(ByRef eRegionId As IMessage.Region, ByRef iMessageId As Integer, _
                              ByRef eClassification As IMessage.Classification, ByRef iOrdinal As Integer) _
                              Implements Eplan.EplApi.EServices.IMessage.OnRegister
          eRegionId = IMessage.Region.Externals
          iMessageId = 25
          eClassification = IMessage.Classification.Error
          iOrdinal = 20
          Return
       End Sub 'OnRegister
    
       Public Function GetMessageText() As System.String Implements Eplan.EplApi.EServices.IMessage.GetMessageText
          ' TODO: Provide text from resource in active GUI language
          Return "Message text for %1!s! from Eplan.EplAddIn.Demo.Messages"
       End Function 'GetMessageText
    
       Public Sub DoHelp() Eplan.EplApi.EServices.IMessage.DoHelp
          new Decider().Decide(EnumDecisionType.eOkDecision, "DoHelp was called!", "Eplan.EplAddIn.Demo.Messages", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK
       End Sub 'DoHelp ' TODO: activate help for this message
    End Class 'Message
    

    A registered message can be written to the message database with help of the MessageManager class. 

    Eplan.EplApi.EServices.MessageManager oMessageMgr = new Eplan.EplApi.EServices.MessageManager();
    Eplan.EplApi.DataModel.ProjectManager oPM= new Eplan.EplApi.DataModel.ProjectManager();
    Eplan.EplApi.DataModel.Project oProject= oPM.CurrentProject;
    if (oProject != null)
    {
        Eplan.EplApi.DataModel.Page[] arrPages = oProject.Pages;
        Eplan.EplApi.DataModel.Function[] arrFunction= arrPages[5].Functions;
        Eplan.EplApi.DataModel.StorableObject oObject1= arrFunction[0];
        Eplan.EplApi.DataModel.StorableObject oObject2= arrFunction[1];
        oMessageMgr.AddMessage( oProject, Eplan.EplApi.EServices.IMessage.Region.Externals, 25,
         "XYZ", oObject1, false, oObject2, "Additional Text");
    }
    
    Dim oMessageMgr As New Eplan.EplApi.EServices.MessageManager()
    Dim oPM As Eplan.EplApi.DataModel.ProjectManager = New Eplan.EplApi.DataModel.ProjectManager()
    Dim oProject As Eplan.EplApi.DataModel.Project = oPM.CurrentProject
    If Not (oProject Is Nothing) Then
       Dim arrPages As Eplan.EplApi.DataModel.Page() = oProject.Pages
       Dim arrFunction As Eplan.EplApi.DataModel.Function() = arrPages(5).Functions
       Dim oObject1 As Eplan.EplApi.DataModel.StorableObject = arrFunction(0)
       Dim oObject2 As Eplan.EplApi.DataModel.StorableObject = arrFunction(1)
       oMessageMgr.AddMessage(oProject, Eplan.EplApi.EServices.IMessage.Region.Externals, 25, "XYZ", oObject1, False, oObject2, "Additional Text")
    End If
    

     

    Overriding text of an existing message 

    It is not possible to change an existing verification by overriding it via API (by setting the same name and a higher Ordinal number). You can however override an existing message and by this change the standard message text to your own text. You need to implement a message with the dame number and region, but use a higher iOrdinal, e.g. 50. Other properties of the message are not influenced. 

    The following example shows, how to override the existing 007005 "Device without main function." message: 

    C#
    Copy Code
    ///
    /// This function returns the message text.
    /// One verification needs always exactly one message text.
    ///
    public string GetMessageText()
    {
       return "This device has absolutely no main function!!!!";
    }
    
    ///
    /// This is the registration function of the message belonging to the verification.
    /// Parameters:
    /// message region
    /// message number
    /// classification: error, message, or info.
    /// overload priority
    public void OnRegister(ref String strCreator, ref Eplan.EplApi.EServices.IMessage.Region eRegion, ref int iMessageId, ref Eplan.EplApi.EServices.IMessage.Classification eClassification, ref int iOrdinal)
    {
       strCreator = "de.Eplan.Demo";
       eRegion = IMessage.Region.Devices;
       iMessageId = 5;
       eClassification = IMessage.Classification.Error;
       iOrdinal = 50; // higher than 20
    }
    
    See Also