Plugin Compliance
Overview
Synthiam is committed to offer users a secure and dependable robot development environment. Due to the high expectation of efficient, dependable and secure from users, there are a few dependencies and restrictions which we enforce in your plugins during review.
Avoid Length GUI Thread Processing
It is very convenient to throw a bunch of code into an event raised by a GUI widget, such as a button or checkbox. When code is executed in an event raised by the user interface, it runs in the thread of that object. This means lengthy code will delay/pause the user interface experience until the code has completed and processing is returned to the GUI thread. This behavior must be reduced at all cost by using events, threading or background workers.
Events
.Net framework provides a number of events for controls, forms and such. Additionally, thr ARC framework provides events for various activities. It is highly preferred to use Events rather than Timers. This includes servo movements, new camera frames, adding/removing controls to workspace, and more. It's good etiquette to unsubscribe from events when your plugin is being closed in the OnClosing() event. If you do not unsubscribe from events, the .Net framework will not know your plugin and respective controls have been disposed, and therefore it may still attempt to execute the method. Notice that an unsubscribe from event is a -= and a subscribe to event is +=
Code:
public MyPluginForm() {
// Subscribe to events to monitor control activity on the workspace
OnBehaviorControlAdded += FormMain_OnBehaviorControlAdded;
OnBehaviorControlRemoved += FormMain_OnBehaviorControlRemoved;
}
private void FormMain_OnBehaviorControlAdded(object newControl, int page) {
MessageBox(string.Format("{0} has been added to the workspace #{1}", newControl.Text, page));
}
private void FormMain_OnBehaviorControlRemoved(object removedControl) {
MessageBox(string.Format("{0} has been removed from the workspace", removedControl.Text);
}
private void MyPluginForm_FormClosing(object sender, FormClosingEventArgs e) {
// Unsubscribe from events that I subscribed to while my plugin is going away
OnBehaviorControlAdded -= FormMain_OnBehaviorControlAdded;
OnBehaviorControlRemoved -= FormMain_OnBehaviorControlRemoved;
}
Timers
One of the most common timers that is used from convenience is System.Windows.Forms.Timer, which is heavily frowned upon and will always have your plugin revoked from public access. An alternative and accepted timer for your background worker is System.Timers.Timer.
The difference between these two timers is trivial programatically, but vast in their operational behavior. The System.Windows.Forms.Timer will raise the elapsed event in the user interface thread, while the System.Timers.Timer will raise the event in a background thread.
As a new programmer, you may be familiar with the behavior of System.Windows.Forms.Timer not raising the elapsed event until the previous event has completed. With System.Timers.Timer, if your last elapsed event has not completed, a new one will still be raised. Avoid using a Lock() statement for this behavior, and instead use a boolean variable shown in this example...Code:
System.Timers.Timer _timer;
bool _isRunning = false; // variable to ensure timer runs once at a time
public FormMaster() {
InitializeComponent();
_timer = new System.Timers.Timer();
_timer.Elapsed += _timer_Elapsed;
_timer.Interval = 100;
_timer.Start();
}
void _timer_Elapsed(object sender, System.Timers.ElapsedEventArgs e) {
// Check if another copy of the time event is running, if so get out
if (_isRunning)
return;
_isRunning = true;
try {
// Do some work
} catch (Exception ex) {
// Uh oh!
} finally {
_isRunning = false;
}
}
Cross-Thread Invoking
While new programmers may feel comfort placing code in events owned by GUI widgets in the user interface thread, there is a different experience when working in a background thread. A background thread will not be able to modify parameters of a GUI object that exists on a different thread. This is called a Cross-Threading Exception. ARC has a helper class to make life easy for you, which is ARC.Invokers. You will need to use Invokers when updating UI components from System.Timers.Timer or most events that aren't triggered by UI. The Invokers class will check if an invoke is required.Code:
void _timer_Elapsed(object sender, System.Timers.ElapsedEventArgs e) {
if (_isRunning)
return;
_isRunning = true;
try {
EZ_Builder.Invokers.SetText(textbox1, "Here is a number: {0}", 5);
EZ_Builder.Invokers.SetChecked(checkbox1, false);
EZ_Builder.Invokers.SetBackColor(button1, System.Drawing.Color.Red);
} catch (Exception ex) {
// Uh oh!
} finally {
_isRunning = false;
}
}
User Configuration Settings
Never under any circumstances save user configuration settings in a separate project file. Always save user configuration settings in the ARC Project File using the tutorial step for Saving/Loading Configuration. Plugins that save configuration data locally to the drive will be revoked from public status. This is to ensure a seamless user experience within the ARC environment. If you have questions about saving custom user data, please inquire on the community forum for assistance.
Exception Handling
Always wrap code in Try {} Catch {} to avoid unhandled exceptions, which will exit ARC. Your plugin will execute under the ARCmaster assembly. If your plugin throws an error that is not handled within an exception, the ARC instance may close. Code:
try {
// do some work
} catch (Exception ex) {
EZ_Builder.EZBManager.Log("Error in control '{0}'. Message: {1}", this.Text, ex.Message);
}