You can create and name custom events, called user events, to carry data that you define. User events allow different parts of an application to communicate asynchronously. Unlike user interface events, which require direct user interaction with front panel objects, user events allow you to create an application that responds to programmatic changes on objects. You can handle both user interface events and programmatically generated user events in the same Event structure.

What to Use

Use the following block diagram objects to create a user event.
  • Create User Event—Create User Event
  • —Register For Events
  • —Event Structure
  • — Generate User Event
  • — Unregister For Events
  • —Destroy User Event

    • What to Do

    Create the following block diagram to build a user event that programmatically carries data you define.


    A screenshot of LabVIEW G code containing the functions listed above.

    The following list describes important details about the previous diagram.

  • 1—To define a user event, wire a block diagram object to the Create User Event function. The input for the Create User Event function is an individual element or a cluster whose name becomes the name of the user event and whose data type defines the data type for the event. Furthermore, LabVIEW uses owned labels to identify the data the user event carries, so label the input data—or each element of the input data—with a descriptive owned label. You must provide a label on the input data for the user event to appear in the Event Data Node of an Event structure. In the previous block diagram, the name of the user event is My User Event, and the name of the event data item is string
  • 2—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. Use this refnum as a reference to the event name and data type when registering for events and generating a user event.
  • 3— Use the Register For Events function to dynamically register the user event. You can wire a combination of user events and user interface events to the Register For Events function.
  • 4— 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. To display the dynamic event terminal, right-click the Event structure and select Show Dynamic Event Terminals. The user event data items appear in the Event Data Node on the left border of the Event structure.
  • 5—To add more data items to the Event Data Node, vertically resize the node. Use the Event Data Node to access any event data element associated with a particular event.
  • 6— 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.
  • 7—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.
    Note 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.
  • 8— Use the Unregister For Events function and the Destroy User Event function to release the associated events and the user event reference. LabVIEW unregisters all events and destroys existing user events automatically when the top-level VI finishes running. However, to conserve memory resources, National Instruments recommends that you unregister and destroy user events explicitly, especially in an application that runs for a long period of time.

    • Caveats and Recommendations

    • You cannot register for a user event statically.
    • You can register for the same user event multiple times by using separate Register For Event functions. In this situation, each queue associated with an event registration refnum receives a copy of the user event and associated event data each time the Generate User Event function executes.
    • User events are notify events and can share the same event case of an Event structure as user interface events or other user events.
    • 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.

    Examples

    Refer to the labview\examples\Dialog and User Interface\Events\Events.lvproj for examples of dynamically registering events.

    Refer to the User Event Generation VI in the labview\examples\Dialog and User Interface\Events directory for an example of using user events.