Custom EZ-Script Function

The EZ-Script engine has two event to add your own custom EZ-Script functions for users to use. The two different events will call before (Override) and after (Additional) the EZ-Script executor. That means you can either override existing commands or add new commands.

Additional Commands
Adding a command extends the existing commandset of EZ-Script. The example below demonstrates adding a new command to EZ-Script called "SetColor()".

Code:


SetColor(20, 100, 20)


The ExpressionEvaluation.FunctionEval.AdditionalFunctionEvent event is raised. Your plugin may attach to this event and process functions for the script.

Here is an example plugin that creates a user defined function called SetColor(): https://synthiam.com/Software/Manual/User-Defined-Function-Example-15864

Code:


using System;
using System.Drawing;
using System.Windows.Forms;

namespace User_Defined_Function_Example {

  public partial class FormMaster : EZ_Builder.UCForms.FormPluginMaster {

    public FormMaster() {

      InitializeComponent();
    }

    private void FormMaster_Load(object sender, EventArgs e) {

      // Intercept all unknown functions called from any ez-script globally.
      // If a function is called that doesn't exist in the ez-script library, this event will execute
      ExpressionEvaluation.FunctionEval.AdditionalFunctionEvent += FunctionEval_AdditionalFunctionEvent;
    }

    private void FormMaster_FormClosing(object sender, FormClosingEventArgs e) {

      // Disconnect from the function event
      ExpressionEvaluation.FunctionEval.AdditionalFunctionEvent -= FunctionEval_AdditionalFunctionEvent;
    }

    /// 
    /// This is executed when a function is specified in any ez-scripting that isn't a native function.
    /// You can check to see if the function that was called is your function.
    /// If it is, do something and return something.
    /// If you don't return something, a default value of TRUE is returned.
    /// If you throw an exception, the ez-script control will receive the exception and present the error to the user.
    /// 
    private void FunctionEval_AdditionalFunctionEvent(object sender, ExpressionEvaluation.AdditionalFunctionEventArgs e) {

      // Check if the function is our function (SetColor)
      if (!e.Name.Equals("setcolor", StringComparison.InvariantCultureIgnoreCase))
        return;

      // Check if the correct number of parameters were passed to this function
      if (e.Parameters.Length != 3)
        throw new Exception("Expects 3 parameters. Usage: SetColor(red [0-255], green [0-255], blue [0-255]). Example: SetColor(20, 200,100)");

      // Convert the parameters to datatypes
      byte red = Convert.ToByte(e.Parameters[0]);
      byte green = Convert.ToByte(e.Parameters[1]);
      byte blue = Convert.ToByte(e.Parameters[2]);

      // Do something
      EZ_Builder.Invokers.SetBackColor(label1, Color.FromArgb(red, green, blue));

      // Return something. Good idea to return TRUE if your function isn't meant to return anything
      e.ReturnValue = true;
    }
  }
}



Override Commands
Override commands will replace the existing EZ-Script command with your own version. This means you can intercept the command and handle the logic yourself. An example of this functionality is in the Ultrasonic Ping Sensor control, which replaces the GetPing() command with it's own version.

*Note: This event has OverrideFunctionEventArgs() which has a IsHandled(bool) that must be set if you hanlded the return object.

The ExpressionEvaluation.FunctionEval.OverrideFunctionEvent event and your logic must exist in there to override the existing command. If you expect a different number of parameters, you can still return and let the main EZ-Script handle it by not setting IsHandled in the OverrideFunctionEventArgs.

Code:


using ExpressionEvaluation;
using EZ_B;
using EZ_Builder.Config;
using EZ_Builder.Scripting;

namespace EZ_Builder.UCForms {

  public partial class FormPing : FormMaster {

    public FormPing() {

      InitializeComponent();

      progressBar1.Maximum = EZ_B.HC_SR04.MAX_VALUE;

      // Set the override event
      ExpressionEvaluation.FunctionEval.OverrideFunctionEvent += FunctionEval_OverrideFunctionEvent;
    }

    private void FormPing_FormClosing(object sender, FormClosingEventArgs e) {

      // detach from the override event
      ExpressionEvaluation.FunctionEval.OverrideFunctionEvent -= FunctionEval_OverrideFunctionEvent;
    }

    private void FunctionEval_OverrideFunctionEvent(object sender, ExpressionEvaluation.OverrideFunctionEventArgs e) {

      if (e.Name.Equals(OpCodeReadEnum.getping.ToString(), StringComparison.InvariantCultureIgnoreCase)) {

        FunctionEval.CheckParamCount(e.Name, e.Parameters, 2);

        string triggerStr = e.Parameters[0].ToString();
        string echoStr = e.Parameters[1].ToString();
        HelperPortParser cmdTrig = new HelperPortParser(triggerStr);
        HelperPortParser cmdEcho = new HelperPortParser(echoStr);

        if (cmdTrig.DigitalPort != _cf.Ping.PingTriggerPort ||
            cmdTrig.BoardIndex != _cf.Ping.EZBIndex ||
            cmdEcho.DigitalPort != _cf.Ping.PingEchoPort ||
            cmdEcho.BoardIndex != _cf.Ping.EZBIndex)
          return;

        if (!Invokers.GetCheckedValue(cbPause))
          return;

        if (cmdTrig.BoardIndex != cmdEcho.BoardIndex)
          throw new Exception("Trigger and Echo ports must be on the same EZ-B");

        if (!EZBManager.EZBs[cmdTrig.BoardIndex].IsConnected)
          throw new Exception(string.Format("Not connected to EZ_B {0}", cmdTrig.BoardIndex));

        int value = EZBManager.EZBs[cmdTrig.BoardIndex].HC_SR04.GetValue(cmdTrig.DigitalPort, cmdEcho.DigitalPort);

        updateDisplayData(value);

        e.ReturnValue = value;
        e.IsHandled = true;

        return;
      }
    }
  }
}