If you create the TestStand Engine as an ActiveX control, the easiest way to handle user interface messages is to implement the UIMessageEvent callback sequence for the ActiveX control. Whenever the engine sends a user interface message for an application, the engine calls the callback with a UIMessage object as a parameter.

Note When you use a programming language such as C# or Microsoft Visual Basic .NET that uses garbage collection to dispose of objects, you must explicitly acknowledge messages when you handle user interface messages by calling the UIMessage.Acknowledge method. If you do not call the UIMessage.Acknowledge method, the TestStand Engine cannot send new messages until the garbage collector disposes of the UIMessage object for the previous message, and the application hangs.

If you do not create the engine as an ActiveX control and are not using the TestStand User Interface (UI) Controls, you can handle user interface messages in the following two ways:

  • When you can write a C-callable function in the application development environment (ADE), you can instruct the engine to call such a function by passing its address to the Engine.RegisterUIMessageCallbackEx method. The application thread that calls this method must regularly process Microsoft Windows messages to use this option.
  • When the ADE cannot create C-callable functions, you must complete the following steps to create a polling loop for user interface messages.
    1. Inform the engine that you are polling by setting the Engine.UIMessagePollingEnabled property to True.
    2. Implement a polling loop by periodically checking the Engine.IsUIMessageQueueEmpty property.
    3. If the queue is not empty, call the Engine.GetUIMessage method to obtain the next user interface message from the engine. Do not check the queue again until you complete whatever action the user interface message requires and release all references to the UIMessage object.
    Tip One way to implement a polling loop in an application is to create a Timer callback that polls each time it executes.