While it is important that the user interface is decoupled from other components of the test system, such as test sequence files and process models, it is necessary for the user interface to effectively communicate with these components. This section provides approaches you can use to communicate between these components while still maintaining this modularity.
Communication between the Sequence and the User Interface
While a test is executing, the test system must provide feedback to the operator indicating the current state of the execution, such as which test is running or the current test results. In general, you can use TestStand UI controls to display this information, such as an Execution View and Report View. By connecting these controls to a manager control, they will always update to show the current execution state, as managed by the engine.
In some cases, you may want to display more specific information about the test. The executing sequence or code module must pass this information to the user interface for display or instruct the user interface to take action. In order to communicate this information without introducing coupling, you can use UI messages to implement the communication. The alternative of using a sequence file property or UI variable as a means to communicate creates unwanted dependencies between sequence files and the user Interface. For example, updating a file global from the sequence, then checking its status in the user interface introduces a coupling between the global and the UI. UI messages are preferred for two reasons:
- Independence of UI and sequence files - A user interface should always run with any sequence file, and vice versa. By using UI messages, there is no requirement that certain properties exist in sequence files when using them with the user interface. With UI messages:
- The user interface can execute sequences that do not implement certain messages (the handling code in the user interface simply never executes).
- Sequences that post custom messages can be executed in a UI that is not built to handle them (the UI message is just ignored by the user interface).
- Maintainability - UI messages avoid dependence on Sequence File Properties or UI variables, meaning less to maintain for developers of both sequence files and user interfaces.
For more information on using UI messages, refer to Using TestStand User Interface Messages (UI Messages)
Types of UI Messages
UI messages contain a message ID which indicates the purpose of the message. TestStand defines several UI message IDs, which define messages that are either sent by the engine automatically or are automatically handled by the TestStand user interface controls. For example, the message ID UIMsg_EndExecution (value 4) is sent by the engine after an execution ends. The Manager controls expose many of these UI messages as individual events; in this case, you can define a handler for the ApplicationManager EndExecution event rather than using a UI message event handler directly.
Other UI messages are posted by the default process models, such as the UIMsg_ModelState_Identified (Value: 32), which the process models post after identifying the serial number of the UUT. In addition, you can post predefined or custom UIMessages from your code modules, test sequence(s), or the process model using the Thread.PostUIMessageEx TestStand API method.
A list of UI message IDs, or event codes, can be found in the UIMessageCodes help topic.
You can define your own UIMessages for custom operations, such as updating data in a chart and histogram. When you define custom UIMessages, specify unique event codes starting at the UIMsg_UserMessageBase event code When you post a custom UIMessage, pass the defined event code and the data to be displayed. UI messages provide data fields for numeric, string, or ActiveX data which you specify when calling the postUIMessageEx method. When you define a handler to respond to the UI message in your user interface, this data is exposed as parameters in the event callback.
To define how a user interface handles UI messages, configure the operator interface to run user defined code when a UI message is handled by adding an event callback for one of two Application Manager events:
- UImessage event - this event is fired whenever any UI message is handled by the Application manager. The event callback specified will execute before any default UI message handling operations. The cancel output event argument can be set to True within the callback to override the default event operations.
- UserMessage event - this event is fired only for custom UI messages (those with message ID of 10,000 or greater).
For information on defining event handlers for a user interface, refer to the Handling Events topic in the TestStand help.
Communication from the User Interface to the Executing Test
In some cases, you may want to communicate information from the user interface to the test sequence. However, communication between a sequence and a UI should always be initiated by the sequence, to ensure the sequence is in a state where it’s data can be modified. To accomplish this, the sequence can post a UI message with a custom code, indicating that it is ready for communication. When you post the UIMessage, set the synchronous parameter to True so that the execution waits until the user interface processes the message. When the user interface processes the UIMessage, it retrieves the SequenceContext object and writes or reads certain variables, such as the process model local variables.
In many cases, the UI is not the best place for the user to specify data related to the test. For example, if the data relates to tasks in the process models, a better approach would be to modify or create a configuration entry point, which you can access from the default menu.
For an example demonstrating Posting and Handling UI messages, including using UI messages to gather data from the user interface, refer to the Handling UI Messages shipping example