Execute actions

Single action

In the "Ribbon" chapter, we learned about the command line. This property is used to tell EPLAN what is to be done. The CommandLineInterpreter class is therefore available in the script. It is identical to our graphical command line in the ribbon, but is called by the program code.

We create a new file 01_SingleAction in the folder 02_RunActions. The quickest way to do this is to copy an existing file. However, we can also create a new empty file via the context menu in the Solution Explorer.

In the first example, we execute the action reports to generate the evaluations. This step corresponds to the menu item Tools > Reports > Generate project reports.

To be able to use the CommandLineInterpreter, we must first initialize it. The freely selectable name for our object is cli.

CommandLineInterpreter cli = new CommandLineInterpreter();

If you want to create an object, the structure is the same or similar:

Class objectName = new class();

Then we have to tell the program the following via the command line: Execute Generate project reports.

cli.Execute("reports");

The command is structured as follows:

cli.Execute("ACTIONNAME");

Execute() is the method for executing an action.

The finished script should look like this:

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_01_SingleAction
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();
    cli.Execute("reports");
  }
}

We now execute the script. Evaluation templates and operating resources should be available in the EPLAN project in order to test the program code successfully.

Multiple actions

We now create the file 02_MultipleActions.cs. As the script in the first example only uses one action, it does not make sense to implement this via the program code. A better way would be to execute several actions one after the other.

We have already initialized a CommandLineInterpreter. We can now also use this for all other actions. One CommandLineInterpreter object is therefore sufficient for each function in a script.

Before evaluating the forms (action: reports), we will start a test run. To do this, we proceed similarly to the DeclareEventHandler example and determine the action using Ctrl+\. Wir wählen dazu den Menüpunkt Tools > Review > Check. We then immediately call up the diagnostics dialog, but without actually executing the test run.

You can also execute your own actions. With DeclareAction we have already loaded an action in EPLAN (ActionName). We execute this at the end of the script. We must ensure that the script is also loaded (02_DeclareAction.cs).

CommandLineInterpreter cli = new CommandLineInterpreter();
cli.Execute("XMsgActionStartVerification");
cli.Execute("reports");
cli.Execute("ActionName");

We will now test the script in EPLAN. The scheme can be selected in the dialog that appears for the test run. The evaluations are generated without visual feedback. This can take some time if it is a larger project.

If the script 02_DeclareAction.cs, EPLAN generates an error in the system messages. To show these, select the symbol at the bottom right or go to File > Extras > System messages > System messages.

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_02_MultipleActions
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();

    cli.Execute("XMsgActionStartVerification");
    cli.Execute("reports");
    cli.Execute("ActionName");
  }
}

Action with parameter

As in the ribbon, it is also possible to execute actions with parameters in scripts. In the following example, we will change the format of a text (normal text or path function text) to font size 20.

To do this, we create a script file with the name 03_Action_mit_Parameter.cs. You can also create a test command in the tab by right-clicking on Ribbon > Customize ribbon... > Actions > Set text format.

When adding the command, our command line must have the content shown in .

To map this in the code, the CommandLineInterpreter has the property ActionCallingContext. This is a separate class.

The structure is as shown in the menu ribbon:

• Action name: XGedStartInteractionAction
• Parameter 1: Name
• Value 1: XGedIaFormatText
• Parameter 2: height
• Value 2: 20

To pass the parameters with the action, we initialize our ActionCallingContext similarly to the CommandLineInterpreter:

ActionCallingContext acc = new ActionCallingContext();

It is advisable to choose a descriptive name for each object, e.g. the abbreviation acc. The ActionCallingContext has the method AddParameter(). As the name suggests, this allows us to add the parameter and the corresponding value:

acc.AddParameter("Name", "XGedIaFormatText");
acc.AddParameter("height", "20");

The command is structured as follows:

acc.AddParameter("PARAMETERNAME", "VALUE");

This can be repeated for all possible parameters. We pass the collected parameters and the corresponding values to CommandLineInterpreter with the action.

cli.Execute("XGedStartInteractionAction", acc);

The command is structured as follows:

cli.Execute("ACTIONNAME", ACTIONCALLINGCONTEXT);

We now create any text in EPLAN, select it and then execute the script.

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_03_ActionsWithParameter
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();
    ActionCallingContext acc = new ActionCallingContext();

    acc.AddParameter("Name", "XGedIaFormatText");
    acc.AddParameter("height", "20");

    cli.Execute("XGedStartInteractionAction", acc);
  }
}

Action overloaded

In this section, I must point out something in advance. It is generally recommended not to overload or overwrite actions. This can be very dangerous and lead to EPLAN malfunctioning. Nevertheless, there are use cases for overwriting an action. This means that the original action is not executed but, for example, a self-programmed action.

There are actions in EPLAN that require careful attention, as there is no way to undo them, for example. We want to output a message for the action Synchronize system master dataw, in addition to the warning from EPLAN, if users execute it.

We create the file 04_ActionOverloading.cs. To do this, we need the name of the original action, which can be found in the diagnostics dialog (XSDShowMatchingMasterDialogAction).

We declare our method with the attribute [DeclareAction("XSDShowMatchingMasterDialogAction", 50)]. As you may recognize, the attribute differs from the already known DeclareAction. An ordinal number is specified, which can be understood as the priority of the action. With 50 we ensure that the action overwrites the one used by EPLAN.

We display a MessageBox with "Caution".

MessageBox.Show("Warning!");

Every action requires a ActionCallingContext. We create this and search for the original action, which we then execute. This works as follows:

ActionCallingContext acc = new ActionCallingContext();
Eplan.EplApi.ApplicationFramework.Action action =
  new ActionManager().FindBaseActionFromFunctionAction(false);
action.Execute(acc);

We load the script and test the functionality. A warning should now be displayed. The finished script looks like this:

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;
using System.Windows.Forms;

public class _02_RunActions_04_ActionOverloading
{
  [DeclareAction("XSDShowMatchingMasterDialogAction", 50)]
  public void Function()
  {
    MessageBox.Show("Warning!");

    ActionCallingContext acc = new ActionCallingContext();
    Eplan.EplApi.ApplicationFramework.Action action =
      new ActionManager().FindBaseActionFromFunctionAction(false);
    action.Execute(acc);
  }
}