Working with the TestStand Simple User Interface - C#.NET

C# .NET

The simple user interface implements the following execution states. Refer to the topics below for the functional details of each state.

• Initializing
• 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:

 <TestStand Public>\UserInterfaces\Simple\CSharp\TestExec.sln

For similar information on LabVIEW or LabWindows/CVI based implementations of the TestStand simple user interface, see the following documents:

• Working with the TestStand Simple User Interface - LabVIEW
• Working with the TestStand Simple User Interface - LabWindows/CVI

Initializing

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)

{

       Close();

       GC.Collect(); // force .net garbage collection to ensure all TestStand objects are freed before the TestStand engine unloads                                                    

                GC.WaitForPendingFinalizers();

}

The simple user interface example registers the following events:

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. 

axApplicationMgr.ConnectCommand(axLoginLogoutButton,

CommandKinds.CommandKind_LoginLogout,           //Type of command to connect

0,

CommandConnectionOptions.CommandConnection_NoOptions);

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:

Shutting Down

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 Handling

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.

Adding new TestStand Controls

You can customize the user interface by adding additional UI controls. In order to make your new controls function, you must connect them to a manager control. 

To add a new control to the simple user interface, follow the steps below. In this example, you will create a new button to launch the TestStand station options dialog box.

axApplicationMgr.ConnectCommand(

axStationOptsButton,                                   //Visible Control

CommandKinds.CommandKind_ConfigureStationOptions,      //command type

0,

CommandConnectionOptions.CommandConnection_NoOptions);

Handling Additional Events

To initiate an action in response to a TestStand event, create a new callback function using the properties pane in the designer. In this example, you will create a callback to handle user generated UIMessages.

In the designer, select the control that defines the event you are handling. In the properties pane, select the Events icon () to view the available events.

To create an event callback, double-click the desired event. The new callback is automatically assigned to the event.

// handles custom UI messages - UI messages with event code greater than UserMessage_Base (10000)

private void axApplicationMgr_UserMessage(object sender, NationalInstruments.TestStand.Interop.UI.Ax._ApplicationMgrEvents_UserMessageEvent e)

{

       switch (e.uiMsg.Event)

       {

              case(UIMessageCodes.UIMsg_UserMessageBase + 1):

                     //Code to handle custom UI message

                     break;

       }

}

Adding Native Environment Controls

To add native controls to the user interface, create the control in the designer and use an event callback function to add functionality, as you would in a typical .NET user interface application.  Additionally, you can implement some TestStand functionality with native controls using the GetCommand and Command.Execute methods, as shown in the example below. Any of the manager controls can call the GetCommand method to access the connections implemented by each control.

//launch the Configure Adapters dialog

private void cfgAdaptersButton_Click(object sender, EventArgs e)

{

   axApplicationMgr.GetCommand(CommandKinds.CommandKind_ConfigureAdapters).Execute(true);

}

National Instruments recommends using the Visible UI controls whenever possible to access the built-in features of these manager controls.