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:

The parameters of the function OnRegister() define the properties of the message and how it is registered in EPLAN.
The function GetMessageText() returns -- on request of EPLAN -- the message text, which is displayed in dialogs.
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
Dim message as Decider = New Decider
    message.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 }

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
}

Reference

Message Class

IMessage Interface

Send Feedback