The simple user interface implements the following execution states. Refer to the topics below for the functional details of each state.
This user interface example is located in the following directory:
<TestStand Public>\UserInterfaces\Simple\CVI\TestExec.cws
For similar information on LabVIEW or LabWindows/CVI based implementations of the TestStand simple user interface, see the following documents:
In the initialization phase of execution, the UI performs typical startup tasks:
Once complete, the interface calls the SetUpActiveXControls function, which implements the remainder of initialization, connects manager controls to visible controls, and configures callbacks to handle TestStand events. In this function, the GetObjHandleFromActiveXCtrl() function obtains the ActiveX handles in the gMainWindow global.
The user interface maintains a gMainWindow global variable, which contains ActiveX handles for the following TestStand UI Controls:
Because the gMainWindow is an instance of the MainPanel Type definition, you can easily add new references to the type definition when making additions to the UI.
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.
In the SetupActiveXControls function, the UI registers callback functions to execute when these specific TestStand Events occur using the Event Callback Registration functions in the NI TestStand UI Controls Library.
These registration functions allow you to specify callback functions that execute when a specified TestStand event occurs. For example, the registration function below specifies that the ApplicationMgr_OnExitApplication() function should execute when the ExitApplication event is generated:
errChk( TSUI__ApplicationMgrEventsRegOnDisplaySequenceFile(
gMainWindow.applicationMgr, //control generating the event
ApplicationMgr_OnDisplaySequenceFile, //Function to call when event occurs
NULL,
1,
NULL));
The callback function has a specific prototype based on the particular event being handled. The ApplicationMgr_OnExitApplication function is shown below.
// the ApplicationMgr sends this event to request that the UI display a particular sequence file
HRESULT CVICALLBACK ApplicationMgr_OnDisplaySequenceFile(
CAObjHandle caServerObjHandle,
void *caCallbackData,
TSUIObj_SequenceFile file,
enum TSUIEnum_SequenceFileDisplayReasons reason)
{
int error = 0;
tsErrChk( TSUI_SequenceFileViewMgrSetByRefSequenceFile(
gMainWindow.sequenceFileViewMgr,
&errorInfo, file));
Error:
DisplayError(error);
return error < 0 ? E_FAIL : S_OK;
}
The Simple user interface example registers the following events:
Event Name | Event Description | Callback VI Functionality |
DisplaySequenceFile | Occurs when you open a sequence file directly or when TestStand sends a UIMsg_OpenWindows event. | Sets a newly opened sequence file as the current sequence file. The newly opened file is displayed in the Sequence File combo box. |
ExitApplication | Occurs when the application has completed the shutdown process.
| Generates the Quit Application User Event, which allows the User Interface to begin shutdown. This user event is created in the Register Event Callbacks state immediately before the Register Event Callback function.
|
DisplayExecution | Occurs when a visible execution starts, when an execution breaks, or in response to a UIMsg_OpenWindow or 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. |
Wait | Occurs when the application is performing lengthy tasks. | Sets the mouse cursor to the wait cursor for lengthy operations, and sets the cursor back to the default cursor when the lengthy operation completes. |
ReportError | Occurs when an error is reported. This event notifies the application of errors that occur while the user operates connected controls. Calling the ApplicationMgr.RaiseError event also calls the ReportError event. | Reports errors generated by TestStand in a dialog. |
In the simple user interface example, the ApplicationManager control generates each specified control, but other controls generate events as well.Refer to the Handling Events help topic for more information about using the Event Registration Functions to handle TestStand events.
In the SetUpActiveXControls funtion, the manager UI controls are connected to the visible controls to specify the functionality of the visible control. Functions of the manager controls implement the connections For example, the following statement connects the Login/Logout button to the manager control and specifies that the button should trigger the login/logout command.
tsErrChk( TSUI_ApplicationMgrConnectCommand(gMainWindow.applicationMgr,
&errorInfo,
gMainWindow.loginLogoutBtn, //control reference
TSUIConst_CommandKind_LoginLogout, //type of command to connect
0,
TSUIConst_CommandConnection_NoOptions,
NULL));
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 help topic for more information about the available types of connections.
When using a connectCommand function, 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 commandKind TSUIConst_CommandKind_LoginLogout, which gives the Login/Logout button its specific functionality. Refer to the CommandKinds Enumeration 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.
After the SetupActiveXControls function completes, the main function calls the TSUI_ApplicationMgrStart function. This function 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. After starting, TestStand displays the user interface and calls the RunUserInterface(), which does not return until the QuitUserInterface() function is called. The remainder of the user interface execution waits for TestStand and CVI events.
After starting the TestStand Application manager, the user interface waits for events to occur and handles them using the registered callback functions.
In addition to TestStand event functions, the user interface handles two CVI events. For example, the MainPanelCallback Handles the EVENT_CLOSE event, which occurs when the user closes the panel.
int CVICALLBACK MainPanelCallback(
int panel,
int event,
void *callbackData,
int eventData1,
int eventData2)
{
switch (event)
{
case EVENT_CLOSE: // user clicked on window close box
ExitApplication(); // this function displays error, if any
}
return 0;
}
In the ExitApplication function,calling the TSUI_ApplicationMgrShutdown function starts the shutdown process. If the function returns a value of “ True,” the TestStand engine has completed shutdown and the shutdown case can execute. Otherwise, the user interface must continue to handle events until the Exit Application Event User Event is generated.
The following table describes the two CVI events handled by this event structure::
Event Name | Event Description | Functionality when the event occurs |
MainPanelCallback - EVENT_CLOSE event | 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.
| Calling the TSUI_ApplicationMgrShutdown function starts the shutdown process. If the function returns a value of “True,” the TestStand engine has completed shutdown and the QuitUserInterface() is called to close the application. Otherwise, the application closes after the ExitApplication TestStand event is handled.
|
MainCallback - EVENT_END_TASK event | Occurs when Windows shutsdown or when the user selects Close from the context menu on the application's task bar item. | The behavior is similar to EVENT_CLOSE but the application closes when the machine is shutting down, even if TestStand shutdown is incomplete. |
Calling the ApplicationManager Shutdown method starts the shutdown process. If the method returns a value of “True,” the TestStand engine has completed shutdown and the shutdown case can execute. Otherwise, the UI continues handling events until the ExitApplication TestStand event is generated, which indicates that the engine has been shut down.
Once the TestStand engine has completed shutdown, the following operations occur:
Error information in the simple user interface example is tracked by wrapping TestStand UI functions with the tsErrChk macro, which checks for any errors that occurred in the function call. This macro also translates the ActiveX error information into an error code and description.
If an error occurs, the execution moves to the “Error:” label to handle the error. In this section, the DisplayError function is called to display the error to the user using the TestStand Utility function TS_DisplayError.
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 window.
typedef struct
{
Int panel;
CAObjHandle engine;
// ActiveX control handles:
(...)
CAObjHandle loginLogoutBtn;
CAObjHandle exitBtn;
CAObjHandle stationOptBtn; //new button
} MainPanel;
errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel,
MAINPANEL_ STATIONOPTBTN,
&gMainWindow.stationOptBtn));
tsErrChk( TSUI_ApplicationMgrConnectCommand(
gMainWindow.applicationMgr, //manager control
&errorInfo,
gMainWindow.stationOptsBtn, //visible control
TSUIConst_CommandKind_ConfigureStationOptions, //command type
0,
TSUIConst_CommandConnection_NoOptions,
NULL));
To initiate an action in response to a TestStand event, create a new callback function and register it using an event registration function. Follow the steps below to create a new callback to handle a TestStand event. In this example, you will create a callback to handle user generated UIMessages.
errChk( TSUI__ApplicationMgrEventsRegOnUserMessage(
gMainWindow.applicationMgr,
ApplicationMgr_OnUserMessage, //callback function to handle event
NULL, //custom callback data
1,
NULL));
Note: To access custom data in the callback, pass it into the CallbackData parameter of the registration function or use a global variable.
// handles custom UI messages - UI messages with event code greater than UserMessage_Base (10000)
HRESULT CVICALLBACK ApplicationMgr_OnUserMessage(CAObjHandle caServerObjHandle, void *caCallbackData, TSUIObj_UIMessage uiMsg)
{
enum TSEnum_UIMessageCodes uiMsgEvent;
int error = 0;
tsErrChk(TS_UIMessageGetEvent(uiMsg, &errorInfo, &uiMsgEvent));
switch (uiMsgEvent)
{
case (10001):
//Code to handle custom UI Message
break;
}
return S_OK;
Error:
DisplayError(error);
return S_OK;
}
To add native CVI controls to the user interface, create the control in the .uir file and use a control callback function to add functionality, as you would in a typical CVI 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 created by each control.
int CVICALLBACK configureAdaptersCallback (int panel, int control, int event,
void *callbackData, int eventData1, int eventData2)
{
TSUIObj_Command newCommand = NULL;
int error = 0;
switch (event)
{
case EVENT_COMMIT:
//create a new command object to launch the adapter dialog
tsErrChk(TSUI_ApplicationMgrGetCommand(
gMainWindow.applicationMgr,
&errorInfo,
TSUIConst_CommandKind_ConfigureAdapters,
0,
&newCommand));
//execute the command
tsErrChk(TSUI_CommandExecute(newCommand, &errorInfo, VTRUE));
break;
}
Error:
CA_DiscardObjHandle(newCommand);
DisplayError(error);
return error;
}
National Instruments recommends using the Visible UI controls whenever possible to access the built-in features of these manager controls.