Make an EZ-Builder Behavior Control

Example: ControlCommand() Binding

The ControlCommand() is an EZ-Script function which enables users to send commands and parameters to supporting controls from another control. It is how controls communicate. Each control broadcasts a list of commands it supports. These commands are displayed in the Cheat Sheet while users are editing EZ-Script. When a ControlCommand() is executed that has a destination name matching your plugin, an event is triggered in which you will respond.

User-inserted image

An Example
An example of a popular ControlCommand() is starting the video feed in the camera control. Users will add EZ-Script to their program which instructs the Camera Control to begin streaming video from the specified video source.


# EZ-Script example to start the video feed on a camera control
ControlCommand("Camera Control", CameraStart)

You may notice that some ControlCommand() will accept optional parameters. The CameraStart also has an optional parameter, which is the device name.


# EZ-Script example to start the video feed on a camera control specifying device name
ControlCommand("Camera Control", CameraStart, "EZB://")

Example In This Tutorial Step
In this tutorial step, the example will return 4 supported control commands to the Cheat Sheet...

- PauseOn. Which will set a checkbox to Checked state.

- PauseOn, [text]. Which will set a checkbox to Checked state and change the text to the specified value.

- PauseOff. Which will set a checkbox to Unchecked state.

- PauseOn, [text]. Which will set a checkbox to Unchecked state and change the text to the specified value.

Return Supported ControlCommands
In order to let users know what possible control commands are available for your plugin, there is an override method. The method will be executed when users view the Cheat Sheet, or right-click in the EZ-Script code editor.

The method is GetSupportedControlCommands(). It returns an array of objects, which will be cast to string when displayed to the user in the Cheat Sheet. Here is an example to return the PauseOn and PauseOff options to the Cheat Sheet. Notice how parameters are passed with [square parenthesis] for user readability.


public override object[] GetSupportedControlCommands() {

List cmds = new List();

cmds.Add("PauseOn, [text]");
cmds.Add("PauseOff, [text]");

return cmds.ToArray();

As you can see, the syntax commands are returned, including the parameters. Those will be displayed in the Cheat Sheet when the user views it, or right-clicks in the EZ-Script editor. The entire ControlCommand() syntax will be assembled automatically from the information that you return in this method.

For example, the above list will be displayed as such to the user in the Cheat Sheet while editing EZ-Script...


ControlCommand("MyPlugin", PauseOn)
ControlCommand("MyPlugin", PauseOn, [text])
ControlCommand("MyPlugin", PauseOff)
ControlCommand("MyPlugin", PauseOff, [text])

Bind To ControlCommand()
Now that the user is aware of the supported options available in your Cheat Sheet, we will bind to the EZ-Script engine for any calls directed to your control. This is done through an override method which will be raised in the event that a ControlCommand() matches your control.

Some facts to note in this example code...

1) Comparison is case insensitive. We have no idea what case the text will be entered by the user.

2) If no commands match your syntax, the Base() method will notify the EZ-Script engine.

3) If expected parameters are missing or incorrect, you may throw an exception which will be caught by the parent EZ-Script engine.

4) To avoid cross-threading exceptions, there is a fancy helper class EZ_Builder.Invokers which contains methods to manipulate user controls from different threads. The SendCommand() event will always be called from a background thread. This is because the EZ-Script engine will never execute threads on a GUI thread.


public override void SendCommand(string windowCommand, params string[] values) {

if (windowCommand.Equals("PauseOn", StringComparison.InvariantCultureIgnoreCase)) {

EZ_Builder.Invokers.SetChecked(checkbox1, true);

if (values.Length == 1)
EZ_Builder.Invokers.SetText(checkbox1, values[0]);
else if (values.Length > 1)
throw new Exception(string.Format("Only 0 or 1 parameters expected. You passed {0}", values.Length));

} else if (windowCommand.Equals("PauseOff", StringComparison.InvariantCultureIgnoreCase)) {

EZ_Builder.Invokers.SetChecked(checkbox1, false);

if (values.Length == 1)
EZ_Builder.Invokers.SetText(checkbox1, values[0]);
else if (values.Length > 1)
throw new Exception(string.Format("Only 0 or 1 parameters expected. You passed {0}", values.Length));

} else {

base.SendCommand(windowCommand, values);

By using the ControlCommand(), users can send commands to your plugin or configure settings, all from EZ-Script. This gives your plugin the ability to be better customized for the users needs programmatically.

ControlCommand() are usable in Blockly UI, with one exception. Because the Blockly UI does not contain the ability for user defined parameters of the ControlCommand() feature, they are limited to commands with no user parameters. This means that a ControlCommand() with parameters will not display in the Blockly UI.

The ControlCommand() for Blockly is found in the Utility category.
User-inserted image

Viewing the available ControlCommand()'s within blockly, you will see that commands accepting user parameters are not displayed..
User-inserted image

To further the example, here are two control commands in which one will be displayed, and one will not be


# This will be displayed in blockly
ControlCommand("My Control", SetColorRed)
ControlCommand("My Control", SetColorGreen)

# These will not be displayed in Blockly because it accepts a user parameter
ControlCommand("My Control", SetColor, Red)
ControlCommand("My Control", SetColor, Green)

Additional Examples
All of DJ Sures plugins are Open Source and nearly all contain ControlCommand() bindings.

Error: the referenced component" EZ_builder,EZ_B" could not be found, DJ Sure i hope you can help me !
#16   — Edited
User-inserted image
Joinny, you have to add the referencing by following the instructions in this tutorial. They are outlined with step by step to easily follow. Click add references, and browse to the appropriate files as directed in the tutorial. I can’t write anything clearer in response. The step to add references is incredibly clear but you’re skipping it.
The error cannot read the COM file, I downloaded it and when I follow the instructions, I get an error, while other files read normally.
.User-inserted image
#18   — Edited
sorry for me but i tried many different ways but still show the error,I couldn't find EZ_B.dll file even though I downloaded it
None of the required references are in your list. Please follow the tutorial. It explains exactly how to click the browse button and navigate to the folder and select the files.
Sorry, but the reason I can't reference is because there is no file in the EZ_B folder and there is an error : this folder is empty , I am trying to solve it. I would like to thank DJ sure for answering my superfluous questions and I'm sorry for bothering you