The simple user interface implements the following execution states. Refer to the topics below for the functional details of each state.
- Configuring Callbacks to Handle TestStand Events
- Connecting Manager controls to Visible controls
- Starting TestStand
- Waiting for Events
- Shutting Down
- Handling Errors
This user interface example is located in the following directory:
For similar information on LabVIEW or LabWindows/CVI based implementations of the TestStand simple user interface, see the following documents:
The C# user interface is implemented using the Windows form class. When the application starts, a new form is created, and the constructor MainForm() initializes the form based on the .NET designer settings. Then, the MainForm_Load callback is called and registered to the Load event of the form in the designer.
The Mainform_Load() callback connects manager controls to visible controls and starts the TestStand engine. The user interface contains the following types of controls:
- Manager UI controls. These invisible controls handle many of the UI functions. Refer to the Manager UI Controls [link here] help topic for more information about the purpose of these controls.
- Visible UI controls. These controls display TestStand information to the user but require a connection to a manager control in order to function. This connection task is implemented in the Connecting Manager controls to Visible controls execution state. Refer to the Visible UI Controls [link here] help topic for more information about the available visible controls.
- Other references. These references are used by code in the user interface, such as the TestStand Engine reference, and are stored in the gMainWindow structure to ensure that the reference can be accessed in all parts of the UI.
Configuring Callbacks to Handle TestStand Events
TestStand user interface controls generate events to notify an application of user inputs and application events, and allow a user interface to respond when application events occur.
Like typical .NET controls, the events for the TestStand UI controls are shown in the property browser when you select the control in the designer. In the simple user interface, five event callbacks are defined for the ApplicationManager control.
The callback function has a specific prototype based on the particular event being handled. The axApplicationMgr_ExitApplication callback is shown below. In this callback, the UI closes the TestStand UI form and starts .NET garbage collection to ensure all TestStand objects are freed.
// It is now ok to exit, close the form
private void axApplicationMgr_ExitApplication(object sender,System.EventArgs e)
GC.Collect(); // force .net garbage collection to ensure all TestStand objects are freed before the TestStand engine unloads
The simple user interface example registers the following events:
||Occurs when a sequence file is opened directly or in response to a UIMsg_OpenWindows event TestStand sends.
||Sets a newly opened sequence file as the current sequence file. The Sequence File combo box displays the newly added file.
Occurs when the application has completed the shutdown process.
Calls the Close() method to close the UI form and starts .NET garbage collection.
||Occurs when a visible execution starts, when an execution breaks, or in response to a UIMsg_OpenWindow or a UIMsg_GotoLocation user interface message. Use the reason parameter to find out why this event was called.
||Sets the current execution to be the execution in which the event is generated, typically. The Execution View control displays the execution.
||Occurs when the application is performing lengthy tasks.
||Sets the mouse cursor to the wait cursor for lengthy operations and sets it back to the default cursor when the lengthy operation completes.
||Occurs when an error is reported. This event notifies the application of errors that occur while the user operates connected controls. This event is also called when the ApplicationMgr.RaiseError event is called.
||Reports errors generated by TestStand in a dialog.
In the simple user interface example, the ApplicationManager control generates each specified event, but other controls generate events as well. Refer to the Handling Events [link here] help topic for more information about using the Event Registration functions to handle TestStand events.
Connecting Manager Controls to Visible Controls
In the MainForm_Load callback, the manager UI controls are connected to the visible controls to specify the functionality of the visible control. These connections are implemented using methods of the manager controls. For example, the following method connects the Login/Logout button to the manager control and specifies that the button should trigger the login/logout command.
CommandKinds.CommandKind_LoginLogout, //Type of command to connect
Many connection functions are available for each manager control depending on the desired functionality of the visible control. Refer to the subtopics of the Connecting Manager Controls to Visible Controls [link here] help topic for more information about the available types of connections.
When using the connectCommand method, as in the case of the login/logout button, you must specify a commandKind that represents the specific command that will be associated with the visible control. In this case, the function call specifies the command kind CommandKinds.CommandKind_LoginLogout, which gives the Login/Logout button its specific functionality. Refer to the CommandKinds Enumeration [link here] help topic for more information about available commandKinds.
Once a visible control is connected to a manager control, no further code is necessary for the control to function.
Starting the Application
After connecting all of the visible controls, the MainForm_Load callback calls the axApplicationMgr.Start()
method. This method initializes the TestStand engine and launches the user interface. At this point, all visible controls have been connected to manager controls, and TestStand events have been registered to callback functions. The remainder of the user interface execution is spent waiting for events.
Waiting for Events
Most of the user interface execution occurs in the Handle Events state. In this state, the user interface waits for events to occur and processes them using the registered callbacks.
The following table describes the .NET events handled by this event structure:
||Functionality when the event occurs
|Occurs when the form is loaded.
||Connects TestStand Visible controls to manager controls and starts the TestStand Application manager.
Occurs when the user tries to interactively close the user interface by selecting the Close item in the File menu or by clicking the close glyph on the window border.
The shutdown process is started by calling the TSUI_ApplicationMgrShutdown function. If the function returns True, the TestStand engine has completed shutdown, QuitUserInterface() is called to end the application. Otherwise, the application is ended when the ExitApplication TestStand event is handled
|Occurs when Windows shuts down or when the user selects Close from the context menu in the application's task bar item.
||Closes the application if the machine is shutting down, even if TestStand shutdown is incomplete.
Attempts to close the UI, such as clicking the windows close glyph or Exit button, initiate the shutdown process. Before the form is closed, the Mainform_Closing event callback is executed, which calls the axApplicationMgr.Shutdown() method to shut down the TestStand engine.
If this method returns a value of “True,” TestStand has completed shutdown, and the form can be closed. Otherwise, the user interface must remain open until the ExitApplication event has been generated, indicating that the engine has successfully shut down. In this case, the close event is cancelled to prevent the window from closing before shutdown is complete.
Error information in the Simple user interface example is tracked by using the try-catch statement, just as in typical .NET applications. Errors that occur in TestStand methods generate an exception, which is displayed to the user using the messageBox() method.