Actions

In This Topic

What is called an "action" in Eplan?

An action is a procedure or function that can be dynamically registered in Eplan. The action is identified by its name and its overload priority. An action can have any number of parameters, which are passed to and from the action via a so-called ActionCallingContext. Each ribbon button in Eplan is associated with an action that is called up when the ribbon button is clicked.

An add-in can add new actions to Eplan. Actions can be called from the command line and they can be assigned to a new ribbon button. A new action can override an existing action with the same name.

An action is implemented by a class that inherits the interface IEplAction. You need to add an implementation of all the functions of the interface. An add-in can contain an arbitrary number of actions.

There are some differences in how actions are implemented in .NET Framework and .NET 8:

public class CSharpAction: Eplan.EplApi.ApplicationFramework.IEplAction
{
    ///<summary>
    /// This function is called when executing the action.
    ///</summary>
    ///<returns>true, if the action performed successfully</returns>
    public bool Execute(Eplan.EplApi.ApplicationFramework.ActionCallingContext ctx)
    {
         new Decider().Decide(EnumDecisionType.eOkDecision, "CSharpAction was called!", "Eplan.EplAddIn.Demo1", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK);
         // Add your code here

         return true;
    }


    ///<summary>
    /// This function is called by the application framework when registering the add-in.
    ///</summary>
    ///<param name="Name">The action is registered in Eplan under this name</param>
    ///<param name="Ordinal">The action is registered with this overload priority</param>
    ///<returns>true, if OnRegister succeeds</returns>
    public bool OnRegister(ref string Name, ref int Ordinal)
    {
         Name  = "CSharpAction";
         Ordinal    = 20;

         return true;
    }


    ///<summary>
    /// Documentation function for the action, which is called by Eplan on demand                       
    ///</summary>                       
    public void GetActionProperties(ref Eplan.EplApi.ApplicationFramework.ActionProperties actionProperties)
    {                       
    }
}

Public Class VBAction
   Implements Eplan.EplApi.ApplicationFramework.IEplAction

   '''<summary>
   ''' This function is called when executing the action.
   '''</summary>
   '''<returns>true, if the action performed successfully</returns>
   Public Function Execute(ctx As Eplan.EplApi.ApplicationFramework.ActionCallingContext) As Boolean _
     Implements Eplan.EplApi.ApplicationFramework.IEplAction.Execute
      Dim dec As Decider = New Decider
      dec.Decide(EnumDecisionType.eOkDecision, "VBAction was called!", "Eplan.EplAddIn.VBDemo1", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK)
      ' Add your Code here
      Return True
   End Function 'Execute

   '''<summary>
   ''' This function is called by the application framework when registering the add-in.
   '''</summary>
   '''<param name="Name">The action is registered in Eplan under this name</param>
   '''<param name="Ordinal">The action is registered with this overload priority</param>
   '''<returns>true, if OnRegister succeeds</returns>
   Public Function OnRegister(ByRef Name As String, ByRef Ordinal As Integer) As Boolean _
    Implements Eplan.EplApi.ApplicationFramework.IEplAction.OnRegister
      Name = "CSharpAction"
      Ordinal = 20
      Return True
   End Function 'OnRegister

   '''<summary>
   ''' Documentation function for the action, which is called by Eplan on demand.
   '''</summary>
   Public Sub GetActionProperties(ByRef actionProperties As Eplan.EplApi.ApplicationFramework.ActionProperties) _
    Implements Eplan.EplApi.ApplicationFramework.IEplAction.GetActionProperties
   End Sub 'GetActionProperties

End Class 'VBAction

As shown in the example above, please implement the GetActionProperties method if you use the .NET Framework 4.8.1 API.

Example for an action in the new .NET 8 API

For the new .NET 8 API, the functionality of the former GetActionProperties method is now moved to the IEplActionProperties interface. If you want to use it, please implement this interface as well:

C# .NET 8
VB .NET 8

public class CSharpActionNet: Eplan.EplApi.ApplicationFramework.IEplAction, Eplan.EplApi.ApplicationFramework.IEplActionProperties
{
    ///<summary>
    /// This function is called when executing the action.
    ///</summary>
    ///<returns>true, if the action performed successfully</returns>
    public bool Execute(Eplan.EplApi.ApplicationFramework.ActionCallingContext ctx)
    {
         new Decider().Decide(EnumDecisionType.eOkDecision, "CSharpAction was called!", "Eplan.EplAddIn.Demo1", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK);
         // Add your code here

         return true;
    }


    ///<summary>
    /// This function is called by the application framework when registering the add-in.
    ///</summary>
    ///<param name="Name">The action is registered in Eplan under this name</param>
    ///<param name="Ordinal">The action is registered with this overload priority</param>
    ///<returns>true, if OnRegister succeeds</returns>
    public bool OnRegister(ref string Name, ref int Ordinal)
    {
         Name  = "CSharpAction";
         Ordinal    = 20;
         return true;
    }

    ///<summary>
    /// Documentation function for the action, which is called by Eplan on demand                      
    /// Implementation of IEplActionProperties.ActionProperties 
    ///</summary>                      
    public void GetActionProperties(ref Eplan.EplApi.ApplicationFramework.ActionProperties actionProperties)
    {                      
    }
}

Public Class VBActionNet
   Implements Eplan.EplApi.ApplicationFramework.IEplAction
   Implements Eplan.EplApi.ApplicationFramework.IEplActionProperties

   '''<summary>
   ''' This function is called when executing the action.
   '''</summary>
   '''<returns>true, if the action performed successfully</returns>
   Public Function Execute(ctx As Eplan.EplApi.ApplicationFramework.ActionCallingContext) As Boolean _
     Implements Eplan.EplApi.ApplicationFramework.IEplAction.Execute
      Dim dec As Decider = New Decider
      dec.Decide(EnumDecisionType.eOkDecision, "VBAction was called!", "Eplan.EplAddIn.VBDemo1", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK)
      ' Add your Code here
      Return True
   End Function 'Execute

   '''<summary>
   ''' This function is called by the application framework when registering the add-in.
   '''</summary>
   '''<param name="Name">The action is registered in Eplan under this name</param>
   '''<param name="Ordinal">The action is registered with this overload priority</param>
   '''<returns>true, if OnRegister succeeds</returns>
   Public Function OnRegister(ByRef Name As String, ByRef Ordinal As Integer) As Boolean _
    Implements Eplan.EplApi.ApplicationFramework.IEplAction.OnRegister
      Name = "CSharpAction"
      Ordinal = 20
      Return True
   End Function 'OnRegister

   '''<summary>
   ''' Documentation function for the action, which is called by Eplan on demand.
   ''' Implementation of IEplActionProperties.ActionProperties 
   '''</summary>
   Public Sub GetActionProperties(ByRef actionProperties As Eplan.EplApi.ApplicationFramework.ActionProperties) _
    Implements Eplan.EplApi.ApplicationFramework.IEplActionProperties.GetActionProperties
   End Sub 'GetActionProperties

End Class 'VBActionNet

Passing parameters to an action and retrieving action parameters

The parameter of the ActionCallingContext type can be used to pass parameters to the action. For extracting the parameter values and for setting parameters (as return parameters!), the class ActionCallingContext provides a set of functions:

public bool Execute(Eplan.EplApi.ApplicationFramework.ActionCallingContext ctx)
{
   String strParamValue=null;
   ctx.GetParameter("Param1", ref strParamValue);
   // Use string parameter ...
   // Fill parameter "ReturnParam" with value "return value".
   // The caller of this action can extract the parameter by ctx.getParameter("ReturnParam", ...)
   String strReturnValue= "return value";
   ctx.AddParameter("ReturnParam", strReturnValue);
   return true;
}

Public Function Execute(ctx As Eplan.EplApi.ApplicationFramework.ActionCallingContext) As Boolean _
   Implements Eplan.EplApi.ApplicationFramework.IEplAction.Execute
   Dim strParamValue As String = String.Empty
   ctx.GetParameter("Param1", strParamValue)
   ' Use string parameter ...
   ' Fill parameter "ReturnParam" with value "return value".
   ' The caller of this action can extract the parameter by ctx.getParameter("ReturnParam", ...)
   Dim strReturnValue As String = "return value"
   ctx.AddParameter("ReturnParam", strReturnValue)
   Return True
End Function 'Execute

Enabling and disabling registered actions

When an action is assigned to a ribbon button, these items are only enabled if the action is registered and enabled. You can enable / disable a registered action via the IEplActionEnable interface.

public class TestAction : Eplan.EplApi.ApplicationFramework.IEplAction, Eplan.EplApi.ApplicationFramework.IEplActionEnable
{
    // IEplAction Members
    #region IEplActionEnable Members
    public bool Enabled(string strActionName, Eplan.EplApi.ApplicationFramework.ActionCallingContext actionContext)
    {
        if (strActionName == "TESTACTION")
        {
            return false;
        }
        else
        {
            return true;
        }
    }
    #endregion
}

Public Class TestAction
   Implements Eplan.EplApi.ApplicationFramework.IEplAction
   Implements Eplan.EplApi.ApplicationFramework.IEplActionEnable

   'IEplAction Members ...
   Public Function Enabled(strActionName As String, actionContext As Eplan.EplApi.ApplicationFramework.ActionCallingContext) As Boolean _
      Implements Eplan.EplApi.ApplicationFramework.IEplActionEnable.Enabled
      If strActionName = "TESTACTION" Then
         Return False
      Else
         Return True
      End If
   End Function 'Enabled

End Class 'TestAction

Reference

Action Class

Actions

Use the Eplan Global Support Portal for feedback and support