User Events

You programmatically can create and name your own events, called user events, to carry user-defined data. Like queues and notifiers, user events allow different parts of an application to communicate asynchronously. You can handle both user interface and programmatically generated user events in the same Event structure.

Creating and Registering User Events

To define a user event, wire a block diagram object, such as a front panel terminal or block diagram constant, to the Create User Event function. The data type of the object defines the data type of the user event. The label of the object becomes the name of the user event. If the data type is a cluster, the name and type of each field of the cluster define the data the user event carries. If the data type is not a cluster, the user event carries a single value of that type, and the label of the object becomes the name of the user event and of the single data element.

The user event out output of the Create User Event function is a strictly typed refnum that carries the name and data type of the user event. Wire the user event out output of the Create User Event function to an event source input of the Register For Events function.

You cannot register for a user event statically. Handle a user event the same way you handle a dynamically registered user interface event. Wire the event registration refnum output of the Register For Events function to the dynamic event terminal on the left side of the Event structure. Use the Edit Events dialog box to configure a case in the Event structure to handle the event. The name of the user event appears under the Dynamic subheading in the Event Sources section of the dialog box.

The user event data items appear in the Event Data Node on the left border of the Event structure. User events are notify events and can share the same event case of an Event structure as user interface events or other user events.

You can wire a combination of user events and user interface events to the Register For Events function.

Generating User Events

Use the Generate User Event function to deliver the user event and associated data to other parts of an application through an Event structure configured to handle the event. The Generate User Event function accepts a user event refnum and a value for the event data. The data value must match the data type of the user event.

If the user event is not registered, the Generate User Event function has no effect. If the user event is registered but no Event structure is waiting on it, LabVIEW queues the user event and data until an Event structure executes to handle the event. You can register for the same user event multiple times by using separate Register For Event functions, in which case each queue associated with an event registration refnum receives its own copy of the user event and associated event data each time the Generate User Event function executes.

Note   To simulate user interaction with a front panel, you can create a user event that has event data items with the same names and data types as an existing user interface event. For example, you can create a user event called MyValChg by using a cluster of two Boolean fields named OldVal and NewVal, which are the same event data items the Value Change user interface event associates with a Boolean control. You can share the same Event structure case for the simulated MyValChg user event and a real Boolean Value Change event. The Event structure executes the event case if a Generate User Event function generates the user event or if a user changes the value of the control.

Unregistering User Events

Unregister user events when you no longer need them. In addition, destroy the user event by wiring the user event refnum to the user event input of the Destroy User Event function. Wire the error out output of the Unregister For Events function to the error in input of the Destroy User Event function to ensure that the functions execute in the correct order.

LabVIEW unregisters all events and destroys existing user events automatically when the top-level VI finishes running. However, National Instruments recommends that you unregister and destroy user events explicitly, especially in a long-running application, to conserve memory resources.

User Event Example

The following block diagram shows how to use user events. A block diagram constant cluster specifies the name of the user event, My Data, and the data type for the event, a string called string. The Register For Events function registers for the user event on the user event refnum. An Event structure in a While Loop waits for the event to occur. In parallel with the While Loop, the Generate User Event function sends the event, which causes the User Event case to execute in the Event structure. When the While Loop terminates, the VI unregisters for the event and destroys the user event.

Build the VI in the following block diagram and then use execution highlighting to see how the event data move from node to node through the VI.

Refer to the labview\examples\general\dynamicevents.llb for examples of dynamically registering events.