Event Structure

Waits until an event occurs, then executes the appropriate case to handle that event.

The Event Structure has one or more subdiagrams, or event cases. Only one event case executes when the structure executes to handle an event. You must place the Event Structure in a While Loop to handle multiple events.

Configure event cases and events from the Item tab. To select the events an event case handles, click Select handled events on the Item tab.

Inputs/Outputs

Event Timeout

Number of milliseconds to wait for an event before timing out.

To enable this terminal, select the Timeout event for at least one event case.

Default value: -1—never time out

1378

Event Selector Label

Part of the structure that indicates which events cause the currently displayed case to execute.

Click the drop-down arrow to view available event cases.
1378

Dynamic Event

Event registration reference or a cluster of event registration references for dynamic event registration.

To enable this terminal, select Use dynamic events on the Item tab.

Use Register for Events to define events programmatically, and then wire the event registration reference to this terminal to access those events from within the Event Structure.

By default, the dynamic event registration terminal on the right border returns the same event registration reference you wire to the input of the dynamic event registration terminal on the left border. However, if you wire a different event registration reference to the input of the dynamic event registration terminal on the right, the terminal on the right no longer carries the same data as the terminal on the left.

You can use a Register For Events node inside of an event case to modify an existing event registration reference dynamically. To modify an existing event registration reference, you must wire event references to the Register For Events node that contain the same data types as the event references contained in the event registration reference you wire to the Register For Events node.

1378

Event Data

Border node that identifies the data the Event Structure returns when an event occurs.

Resize the node to view and select data elements. Time and Index are common to all events. Other data elements vary based on the event you configure.

The order of events in the Event Selector Label determines the Index of the events in an event case that handles more than one event. When more than one event source is configured for an event structure case, Index displays which item in the list of sources generated the event currently being handled. Use Control Reference to find more information on the source that generated the event.

1378

Event Filter

Border node that identifies the event data you can modify before the user interface can process that data.

This node appears in the Event Structure cases that handle filter events. Resize the node to view inputs available for the filter event you select.

Filter events have names that end with a question mark to help you distinguish them from notify events. Use a filter event if you want to discard the event or interact with data associated with a particular user action on the panel before the Event Structure executes a subdiagram of code.

To change event data, wire and modify data items from the Event Data node to the Event Filter node. You can also change the event data by wiring new values to Event Filter node inputs. To completely discard an event, wire a True value to the Discard? input. If you do not wire a value to a data item of the Event Filter node, that data item remains unchanged.

1378

Tunnel

Point through which data enters or exits a structure.

1378
1378

Programming Patterns

  • Execute Code Based on a User Event

Event Timeout

The Event Structure can time out while waiting for notification of an event. The Event Structure executes the timeout event case you create if the structure times out. The Event Structure does not time out if you do not select the Timeout event for at least one event case.

Types of User Interface Events

There are two types of user interface events handled by the Event Structure: notify and filter.

Filter events have names that end with a question mark to help you distinguish them from notify events. In most cases, the VI generates an associated notify event after its corresponding filter event if no event case discarded the event. The notify event has the same name as its corresponding filter event but without the question mark.

The following table describes these types of events and when to use each type:

Notify Filter
Description Informs you that a user action occurred. Allows you to validate or change the event data before the VI performs the default action associated with that event. You can also discard the event entirely to prevent the change from affecting the VI.
Use Case Use if you want to execute a subdiagram of code when the user performs a particular action on the panel. Use if you want to discard the event or interact with data associated with a particular user action on the panel before the Event Structure executes a subdiagram of code.
Dataflow The VI sends a copy of the event, in parallel, to each Event Structure configured to handle the event. The VI sends the event sequentially to each Event Structure configured for the event.
  • The order in which the VI sends the filter event to each Event Structure depends on the order in which you register the events.
  • Each Event Structure must complete the filter event case before the VI can notify the next Event Structure.
  • If an Event Structure case changes any of the event data, the VI passes the changed data to subsequent Event Structures in the chain.
  • If an Event Structure in the chain discards the event, the VI does not pass the event to any Event Structures remaining in the chain.
  • The VI completes processing the user action that triggered the event only after all configured Event Structures handle the event without discarding it.
Example You can configure an Event Structure to execute to handle a Value Change event when the user changes the value of a control. You can configure an Event Structure to discard the Panel Close? event, preventing the user from interactively closing the panel of the VI.

Event Registration

Register events to specify which events you want an Event Structure to handle.

When you register an event, the VI notifies the Event Structure when that particular event occurs. You can register for an event statically or dynamically. A VI that contains an Event Structure automatically performs static event registration when you run it. Use the Register for Events node to perform event registration for dynamic events.

The following table describes the types of event registration and when to use each type.

Static Event Registration Dynamic Event Registration
Description The VI always queues the event sequentially and notifies the Event Structure when the event occurs. The VI queues the event sequentially and notifies the Event Structure when the event occurs only if that event occurs as a result of execution of code in your VI.
Use Case You want the VI to generate events only from user interaction on the panel. You want the VI to generate events as a result of programmatic changes to elements in the VI.
Event Generation Requires user interaction for the VI to generate events. The VI can generate events without direct user interaction with the panel.
  • You can design an application to make programmatic changes, like updating the value of a control from the diagram, and the VI generates events for these changes.
  • You can control when the VI generates events by registering for events in different parts of an application.
  • At run time, you can change which VIs or controls generate events. To change the objects for which the VI generates events, modify the registration information at run time.
Event Handling

Handle events only in the VI where you generate events.

You can configure an Event Structure to specify which user interface events on the panel of a VI you want to handle in each Event Structure case.

Handle events in a subVI in addition to the VI where you generate events.

For example, in a DAQ application, you can create a subVI to handle all of the user interface events, a subVI to handle all custom events, and a subVI to handle all DAQ events for the entire application rather than handling all events in the VI where the events are generated.

Example If you statically register for a Mouse move event on a panel control, the VI queues this event every time the user moves the mouse over that control. If you dynamically register for a user event, the VI queues this event when Generate User Event generates the event.