LabVIEW can generate many different events. To avoid generating unwanted events, use event registration to specify which events you want LabVIEW to notify you about. LabVIEW supports two models for event registration— static and dynamic.
Static registration allows you to specify which events on the front panel of a VI you want to handle in each Event structure case on the block diagram of that VI. LabVIEW registers these events automatically when the VI runs, so the Event structure begins waiting for events as soon as the VI begins running. Each event is associated with a control on the front panel of the VI, the front panel window of the VI as a whole, or the LabVIEW application. You cannot statically configure an Event structure to handle events for the front panel of a different VI. Configuration is static because you cannot change at run time which events the Event structure handles.
Dynamic event registration avoids the limitations of static registration by integrating event registration with the VI Server, which allows you to use Application, VI, and control references to specify at run time the objects for which you want to generate events. Dynamic registration provides more flexibility in controlling what events LabVIEW generates and when it generates them. However, dynamic registration is more complex than static registration because it requires using VI Server references with block diagram functions to explicitly register and unregister for events rather than handling registration automatically using the information you configured in the Event structure.
|Note In general, LabVIEW generates user interface events only as a result of direct user interaction with the active front panel. LabVIEW does not generate events, such as Value Change, when you use shared variables, global variables, local variables, DataSocket, and so on. However, you can use the Value (Signaling) property to generate a Value Change event programmatically. In many cases, you can use programmatically generated events instead of queues and notifiers.|
The event data provided by a LabVIEW event always include a time stamp, an enumeration that indicates which event occurred, and a VI Server reference to the object that triggered the event. The time stamp is a millisecond counter you can use to compute the time elapsed between two events or to determine the order of occurrence. The reference to the object that generated the event is strictly typed to the VI Server class of that object. Events are grouped into classes according to what type of object generates the event, such as Application, VI, or Control. If a single case handles multiple events for objects of different VI Server classes, the reference type is the common parent class of all objects. For example, if you configure a single case in the Event structure to handle events for a numeric control and a color ramp control, the type of the control reference of the event source is Numeric because the numeric and color ramp controls are in the Numeric class. If you register for the same event on both the VI and Control class, LabVIEW generates the VI event first.
|Note Clusters are the only container objects for which you can generate events. LabVIEW generates Control events for clusters, before it generates events for the objects they contain, except in the case of the Value Change event. The Value Change event generates the event on an element in the cluster, then on the cluster itself. If the Event structure case for a VI event or for a Control event on a container object discards the event, LabVIEW does not generate further events.|
Each Event structure and Register For Events function on the block diagram owns a queue that LabVIEW uses to store events. When an event occurs, LabVIEW places a copy of the event into each queue registered for that event. An Event structure handles all events in its queue and the events in the queues of any Register For Events functions that you wired to the dynamic event terminals of the Event structure. LabVIEW uses these queues to ensure that events are reliably delivered to each registered Event structure in the order the events occur.
By default, when an event enters a queue, LabVIEW locks the front panel that contains the object that generated that event. LabVIEW keeps the front panel locked until all Event structures finish handling the event. While the front panel is locked, LabVIEW does not process front panel activity but places those interactions in a buffer and handles them when the front panel is unlocked.
For example, a user might anticipate that an event case launches an application that requires text entry. Since the user already knows text entry is needed, he might begin typing before the application appears on the front panel. If the Lock front panel until the event case for this event completes option is enabled, once the application launches and appears on the front panel, it processes the key presses in the order in which they occurred. If the Lock front panel until the event case for this event completes option is disabled, the key presses might be processed elsewhere on the front panel, since LabVIEW does not queue their execution to depend on the completion of the event case.
Front panel locking does not affect certain actions, such as moving the window, interacting with the scroll bars, and clicking the Abort button.
LabVIEW can generate events even when no Event structure is waiting to handle them. Because the Event structure handles only one event each time it executes, place the Event structure in a While Loop to ensure that an Event structure can handle all events that occur.
|Caution If no Event structure executes to handle an event and front panel locking is enabled, the user interface of the VI becomes unresponsive. If this occurs, click the Abort button to stop the VI. You can disable front panel locking by right-clicking the Event structure and removing the checkmark from the Lock front panel until the event case for this event completes checkbox in the Edit Events dialog box. You cannot turn off front panel locking for filter events.|
When you use events in LabVIEW, consider the caveats and recommendations for doing so.
Static event registration is available only for user interface events. Use the Edit Events dialog box to configure an Event structure to handle a statically registered event. Select the event source, which can be the application, the VI, or an individual control. Select a specific event the event source can generate, such as Panel Resize, Value Change, and so on. Edit the case to handle the event data according to the application requirements.
LabVIEW statically registers events automatically and transparently when you run a VI that contains an Event structure. LabVIEW generates events for a VI only while that VI is running or when another running VI calls the VI as a subVI.
When you run a VI, LabVIEW sets that top-level VI and the hierarchy of subVIs the VI calls on its block diagram to an execution state called reserved. You cannot edit a VI or click the Run button while the VI is in the reserved state because the VI can be called as a subVI at any time while its parent VI runs. When LabVIEW sets a VI to the reserved state, it automatically registers the events you statically configured in all Event structures on the block diagram of that VI. When the top-level VI finishes running, LabVIEW sets it and its subVI hierarchy to the idle execution state and automatically unregisters the events.
Refer to the labview\examples\general\uievents.llb for examples of using static event registration.
Dynamic event registration gives you complete control over which events LabVIEW generates and when it generates them. Use dynamic registration if you want event generation to occur during only part of the application or if you want to change which VIs or controls generate events while your application is running. With dynamic registration, you can handle events in a subVI rather than only in the VI where the events are generated.
Handling dynamically registered events involves the following four main steps:
To dynamically register for events on an object, first obtain a VI Server reference to the object. Use the Open Application Reference and Open VI Reference functions to obtain application and VI references. To obtain a reference for a control, use a Property Node to query a VI for its controls or right-click the control and select Create»Reference from the shortcut menu to create a control reference constant.
Use the Register For Events function to dynamically register for events. You can resize the Register For Events function to show one or more event source inputs. Wire an application, VI, or control reference to each event source input. Right-click each input and select which event you want to register for from the Events shortcut menu. The events from which you can select depend on the VI Server reference type you wire to the event source input. The events on the Events shortcut menu are the same events you see in the Edit Events dialog box when you statically register events. When the Register For Events function executes, LabVIEW registers for the specified event on the object associated with each event source input reference. Once you register events, LabVIEW queues events as they occur until an Event structure handles them. Actions that occur before the function executes do not generate events unless another object previously registered for them.
|Note Unlike a Property Node, the Register For Events function does not require you to wire the top left input. Use this input only when you want to modify an existing registration.|
The dynamic event terminals, available by right-clicking the Event structure and selecting Show Dynamic Event Terminals from the shortcut menu, behave similarly to shift registers. The left terminal accepts an event registration refnum or a cluster of event registration refnums. If you do not wire the inside right terminal, it carries the same data as the left terminal. However, you can wire the event registration refnum or cluster of event registration refnums to the inside right terminal through a Register For Events function and modify the event registration dynamically.
The output of the Register For Events function is an event registration refnum, which is a strict data type LabVIEW uses to propagate information about registered events to the Event structure. You can view the registered events in the Context Help window by idling the cursor over the event registration refnum. After you configure the Register For Events function, wire the event registration refnum output of the Register For Events function to the dynamic event terminal on the left side of an Event structure and configure the Event structure to handle the registered events. Avoid branching an event registration refnum wire because that allows multiple Event structures to pull events from one queue and introduces a race condition that can cause unpredictable behavior.
To configure an Event structure to handle a dynamically registered event, use the Edit Events dialog box. The Event Sources section of the dialog box contains a Dynamic subheading that lists each dynamically registered event source. The names of the event sources are the same names as the references you wired to the Register For Events function connected to the Event structure and are listed in the same order. Select the event source you want from the Dynamic list. Notice that the same event you registered using the Register For Events function appears highlighted in the Events section. After you select the event, edit the case to handle the event data according to the application requirements.
Stop event generation by wiring the dynamic event terminal on the right side of the Event Structure to the event registration refnum input of an Unregister For Events function outside the While Loop that contains the Event structure. When the Unregister For Events function executes, LabVIEW unregisters all events the event registration refnum specifies, destroys the event queue associated with the event registration refnum, and discards any events that remain in the queue. If you do not unregister events, and the user performs actions that generate events after the While Loop that contains the Event structure finishes, LabVIEW queues events indefinitely, which can cause the VI to become unresponsive if you configured the events to lock the front panel. In this situation, LabVIEW destroys the event queue when the VI goes idle.
LabVIEW also unregisters all events automatically when the top-level VI finishes running. However, National Instruments recommends that you unregister events explicitly, especially in a long-running application, to conserve memory resources.
The following block diagram shows how to use dynamic event registration using the Mouse Enter event on a string control as an example.
Refer to the labview\examples\general\dynamicevents.llb for examples of dynamically registering events.
If you register for events dynamically, you can modify the registration information at run time to change which objects LabVIEW generates events for. Wire the top left event registration refnum input of a Register For Events function if you want to modify the existing registration associated with the refnum you wire rather than create a new registration. When you wire the event registration refnum input, the function automatically resizes to show the same events on the same types of references as you specified in the Register For Events function that originally created the event registration refnum. You cannot manually resize or reconfigure the function while the event registration refnum input is wired.
If you wire an object reference to an event source input of a Register For Events function and you also have wired the event registration refnum input, the function replaces whatever reference was previously registered through the corresponding event source input of the original Register For Events function. You can wire the Not a Refnum constant to an event source input to unregister for an individual event. If you do not wire an event source input, LabVIEW does not change the registration for that event. Use the Unregister For Events function if you want to unregister for all events associated with an event registration refnum.
The example in the following block diagram shows how you can dynamically change at run time which objects LabVIEW generates events for. When the following block diagram executes, LabVIEW registers the Numeric reference and waits for an event to occur on the associated Numeric control. When LabVIEW generates a Value Change event for the Numeric control, the Numeric Value Change event case executes a Register For Events function to change the numeric control registered for the Value Change event from Numeric to Numeric 2. If the user subsequently changes the value of the Numeric control, LabVIEW does not generate a Value Change event. However, changes to the Numeric 2 control generate Value Change events. Each time LabVIEW generates a Value Change event for the Numeric 2 control, the Register For Events function executes but has no effect because the Numeric 2 control is already registered for the Value Change event.
|Note You cannot dynamically modify statically registered events.|