You are here: Start » HMI » Handling HMI Events

Handling HMI Events


The HMI model in Adaptive Vision Studio is based on the program loop. A macrofilter reads data from the HMI controls each time before its first filter is executed. Then, after all filters are executed, the macrofilter sends results to HMI. This is repeated for each iteration. This communication model is very easy to use in typical machine vision applications, which are based on a fast image acquisition loop and where the HMI is mainly used for setting parameters and observing inspection results. In many applications, however, it is not only required to use parameters set by the end user, but also to handle events such as button clicks.

To perform certain actions immediately after an event is raised, Adaptive Vision Studio also comes with the HMI subsystem that handles events independently of the program execution process. This allows for creating user interfaces that respond almost in real-time to the user input e.g. clicking button, moving mouse cursor over an object or changing its value. It would not be possible if events were handled solely by the program execution process.

Event Handlers

An event handler is a subprogram in Adaptive Vision Studio that contains the actions to be performed when an associated event occurs. In fact, it is a macrofilter that is executed once for each received event. If there are several HMI controls whose events should trigger the same procedure, one event-handling macrofilter can be used for all of them.

Creating Event Handlers

To create an event handler:

  1. Left-click the HMI control that will be the source of an event and go to its Properties.
  2. Switch to the Events window by clicking the icon:
  3. This will open the Events window with most commonly used events that can be handled. Click the drop-down list next to the event name and select <add new...> as shown below:
    NOTE: There are many more events available. If you want to see the complete list, right-click on the HMI Control, select Edit Ports and Events Visibility... and go to the Events tab.
  4. Define the name of the event handler in the pop-up window:
  5. Some types of events, e.g. mouse move, can send additional information about the performed action. When creating an event handler you need to specify whether input parameters (containing additional information) should be created. If you select this option, the created event handler will have some inputs that can be used in the event-handling algorithm. A practical example of using input parameters is the mouse click event handler on View2DBox HMI control:
    NOTE: When input parameters are used, the event handler is assigned only to the HMI control it was created for, and cannot be used for other controls. To create a universal event-handling macrofilter, which can contain an algorithm executed for several different HMI controls, choose the second option in "Add New Event Handler" pop-up window.
  6. Once the event handler is created, it is available in the Project Explorer:

Queuing Event Handlers

To create applications that handle events efficiently, it is important to understand the mechanism of event-handling macrofilters execution. Especially the way how the HMI subsystem, mentioned earlier in this article, queues them when several events come at short intervals.

When an HMI Control sends an event to signal the occurrence of an action, the HMI subsystem retrieves the event and stores it in a FIFO queue. This queue is then processed in a separate thread dedicated for handling HMI events.

Sample events sequence and a timeline showing the order in which they are handled

This has important implications:
  • Event handlers should not contain any time-consuming algorithms that could delay the execution of subsequent events.
  • Events are always handled one by one. Therefore it is essential to make event-handling procedures as short as possible.
  • All event handlers are executed in parallel to the main program loop, but no two event handlers are executed at the same time.
  • If you use non-free data analysis functions in event handlers, they will get counted for the ThreadLimit license restriction.

Iteration-based Events

Apart from event handlers, it is still possible to create applications in the iteration-based model, where events are available as a standard HMI control's output. Such events are detected by the HMI subsystem independently of the program execution process but have to be handled by this process. Consequently, even though the event is detected instantly, it has to wait until the program enters any macrofilter with an incoming HMI connection related to that event. The value on this connection changes for exactly one iteration and if this particular HMI output is connected in multiple macrofilters, the first read also resets the HMI control's value.

Example of HMI control containing an event signal (outValueChanged) at its output

Until version 5.0, this approach was the only way to handle HMI events. Although event handlers ensure that an event is handled right after the action occurrence, the "old" approach remains in use. Especially in applications where:

  • HMI is mainly used for displaying results and setting the parameters of an algorithm.
  • HMI controls do not change the state and value of each other. For instance, the inEnabled state of one HMI control does not depend on the output of other HMI control.

Iteration-based events are typically used to fulfill the following types of requirements:

  1. Actions – for example, when the user wants to save the current input image to a file after clicking a button.
  2. State Transitions – when the user expects the application to switch to another mode of operation after clicking a button.


When a button (ImpulseButton) is clicked, it will change its outValue output from False to True for exactly one iteration. This output is typically used in one of the following ways:

  1. As the forking input of a variant macrofilter, where the True variant contains filters that will be executed when the event occurs.
  2. As the input of a formula block with a conditional operator (if-then-else or ?:) used within the formula to compute some value in a response to the event.
  3. State Transitions

    Handling events that switch the application to another mode of operation is described in the Programming Finite State Machines article.

    Handling Events in Low Frame-Rate Applications

    The HMI model of Adaptive Vision Studio assumes that the program runs in a fast, continuous loop, with cycles not longer than 100 ms (10 frames per second). If the main loop of the application is slower, e.g. when the camera is triggered and is not receiving any trigger signal for some time, then the HMI will also be slow or halted.

    To solve the problem we need to handle the image processing and the HMI events at different frequencies. The recommended approach is to use an image acquisition filter with the timeout setting (100 ms) and process the images conditionally only in some iterations, while handling the HMI events continuously, at least 10 times per second. This can be done with GigEVision_GrabImage_WithTimeout, GenICam_GrabImage_WithTimeout or with any other image acquisition filter of this kind.

    Below is a sample program structure with two separate step macrofilters handling the image processing part and the HMI event processing part at different frequencies. Note the conditional mode of execution of the "InspectImage" macrofilter.

    An example program structure with a fast cycle of HMI processing and a slow cycle of image analysis.

    Previous: Standard HMI Controls Next: Saving State of HMI Controls