LabVIEW Core 2 Course Manual

Table 1-1. Queue Operations Functions (Continued)

Function Description
Get Queue Status Returns information about the current state of a queue, such
as the number of elements currently in the queue.

Obtain Queue Returns a reference to a queue.

Release Queue Releases a reference to a queue.

Refer to the Queue Operations Functions topic of the LabVIEW Help for a complete list and
description of queue operations.

When used with the producer/consumer design pattern, queues pass data and synchronize the loops
as shown in Figure 1-1.
Figure 1-1. Producer/Consumer Design Pattern (Data) Using Queues

© National Instruments | 1-3

Lesson 1 Moving Beyond Dataflow

The queue is created before the loops begin using the Obtain Queue function. The producer loop
uses the Enqueue Element function to add data to the queue. The consumer loop removes data from
the queue using the Dequeue Element function. The consumer loop does not execute until data is
available in the queue. After the VI has finished using the queues, the Release Queue function
releases the queues. When the queue releases, the Dequeue Element function generates an error,
effectively stopping the consumer loop. This eliminates the need to use a variable to stop the loops.

The following benefits result from using queues in the producer/consumer design pattern:
• Both loops are synchronized to the producer loop. The consumer loop only executes when data
is available in the queue.
• You can use queues to create globally available data that is queued, removing the possibility of
losing the data in the queue when new data is added to the queue.
• Using queues creates efficient code. You need not use polling to determine when data is
available from the producer loop.

Queues are also useful for holding state requests in a state machine. In the implementation of a state
machine that you have learned, if two states are requested simultaneously, you might lose one of
the state requests. A queue stores the second state request and executes it when the first has
finished.

Case Study: Weather Station Project

The weather station project acquires temperature and wind speed data, and analyzes it to determine
if the situation requires a warning. If the temperature is too high or too low, it alerts the user to a
danger of heatstroke or freezing. It also monitors the wind speed to generate a high wind warning
when appropriate.

The block diagram consists of two parallel loops, which are synchronized using queues. One loop
acquires data for temperature and wind speed and the other loop analyzes the data. The loops in the
block diagram use the producer/consumer design pattern and pass the data through the queue.
Queues help process every reading acquired from the DAQ Assistant.

Code for acquiring temperature and wind speed is placed in the producer loop. Code containing the
state machine for analysis of temperature-weather conditions is within the no error case of the
consumer loop. The code using a queue is more readable and efficient than the code using only
state machine architecture. The Obtain Queue function creates the queue reference. The producer
loop uses the Enqueue Element function to add data obtained from the DAQ Assistant to the queue.
The consumer loop uses the Dequeue Element function to get the data from the queue and provide
it to the state machine for analysis. The Release Queue function marks the end of queue by
destroying it. The use of queues also eliminates the need for a shared variable to stop the loops
because the Dequeue Element function stops the consumer loop when the queue is released.

1-4 | ni.com
 LabVIEW Core 2 Course Manual

Figure 1-2 shows the block diagram consisting of a producer and a consumer loop. Data transfer
and synchronization between the loops is achieved by the queue functions.
Figure 1-2. Data Transfer and Synchronization of Parallel Loops Using Queues

C. Event-Driven Programming
Event-driven programming is a method of programming where the program waits on an event to
occur before executing one or more functions. The features of event-driven programming extend
the LabVIEW dataflow environment to allow the user’s direct interaction with the front panel and
other asynchronous activity to further influence block diagram execution.

Events
What Are Events?
An event is an asynchronous notification that something has occurred. Events can originate from
the user interface, external I/O, or other parts of the program. User interface events include mouse
clicks, key presses, and so on. External I/O events include hardware timers or triggers that signal
when data acquisition completes or when an error condition occurs. Other types of events can be
generated programmatically and used to communicate with different parts of the program.
LabVIEW supports user interface and programmatically generated events. LabVIEW also supports
ActiveX and .NET generated events, which are external I/O events.

In an event-driven program, events that occur in the system directly influence the execution flow.
In contrast, a procedural program executes in a pre-determined, sequential order. Event-driven
programs usually include a loop that waits for an event to occur, executes code to respond to the
event, and reiterates to wait for the next event. How the program responds to each event depends
on the code written for that specific event. The order in which an event-driven program executes
depends on which events occur and on the order in which they occur. Some sections of the program

© National Instruments | 1-5

Lesson 1 Moving Beyond Dataflow

might execute frequently because the events they handle occur frequently, and other sections of the
program might not execute at all because the events never occur.

Polling vs Event Structures

Use user interface events in LabVIEW to synchronize user actions on the front panel with block
diagram execution. Events allow you to execute a specific event-handling case each time a user
performs a specific action. Without events, the block diagram must poll the state of front panel
objects in a loop, checking to see if any change has occurred. Polling the front panel requires a
significant amount of CPU time and can fail to detect changes if they occur too quickly.

By using events to respond to specific user actions, you eliminate the need to poll the front panel
to determine which actions the user performed. Instead, LabVIEW actively notifies the block
diagram each time an interaction you specified occurs. Using events reduces the CPU requirements
of the program, simplifies the block diagram code, and guarantees that the block diagram can
respond to all interactions the user makes.

Use programmatically generated events to communicate among different parts of the program that
have no dataflow dependency. Programmatically generated events have many of the same
advantages as user interface events and can share the same event-handling code, making it easy to
implement advanced architectures, such as queued state machines using events.

Event Structure Components

Use the Event structure, shown as follows, to handle events in a VI.

The Event structure works like a Case structure with a built-in Wait on Notification function. The
Event structure can have multiple cases, each of which is a separate event-handling routine. You
can configure each case to handle one or more events, but only one of these events can occur at a
time. When the Event structure executes, it waits until one of the configured events occur, then
executes the corresponding case for that event. The Event structure completes execution after
handling exactly one event. It does not implicitly loop to handle multiple events. Like a Wait on
Notification function, the Event structure can time out while waiting for notification of an event.
When this occurs, a specific Timeout case executes.

The event selector label at the top of the Event structure indicates which events cause the currently
displayed case to execute.

View other event cases by clicking the down arrow next to the case name and selecting another
case from the shortcut menu.

1-6 | ni.com
 LabVIEW Core 2 Course Manual

The Timeout terminal at the top left corner of the Event structure specifies the number of
milliseconds to wait for an event before timing out.

The default is –1, which specifies to wait indefinitely for an event to occur. If you wire a value to
the Timeout terminal, you must provide a Timeout case.

The Event Data Node behaves similarly to the Unbundle By Name function.

This node is attached to the inside left border of each event case. The node identifies the data
LabVIEW provides when an event occurs. You can resize this node vertically to add more data
items, and you can set each data item in the node to access any event data element. The node
provides different data elements in each case of the Event structure depending on which event(s)
you configure that case to handle. If you configure a single case to handle multiple events, the
Event Data Node provides only the event data elements that are common to all the events
configured for that case.

The Event Filter Node is similar to the Event Data Node.

This node is attached to the inside right border of filter event cases. The node identifies the subset
of data available in the Event Data Node that the event case can modify. The node displays different
data depending on which event(s) you configure that case to handle. By default, these items are
inplace to the corresponding data items in the Event Data Node. If you do not wire a value to a data
item of an Event Filter Node, that data item remains unchanged.

Refer to the Notify and Filter Events section of this lesson for more information about filter events.

The dynamic event terminals are available by right-clicking the Event structure and selecting Show
Dynamic Event Terminals from the shortcut menu.

These terminals are used only for dynamic event registration.

Refer to the Using Events in LabVIEW topic of the LabVIEW Help for more information about
using these terminals.

Note Like a Case structure, the Event structure supports tunnels. However, by default
you do not have to wire Event structure output tunnels in every case. All unwired tunnels
use the default value for the tunnel data type. Right-click a tunnel and deselect Use
Default If Unwired from the shortcut menu to revert to the default Case structure

© National Instruments | 1-7

Lesson 1 Moving Beyond Dataflow

behavior where tunnels must be wired in all cases. You also can configure the tunnels to
wire the input and output tunnels automatically in unwired cases.

Refer to the LabVIEW Help for information about the default values for data types.

Using Events in LabVIEW

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, 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.

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

1-8 | ni.com
 LabVIEW Core 2 Course Manual

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 (defer processing of user action)
until this event case 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 (defer processing of user action) until this event case 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 (defer
processing of user action) until this event case completes checkbox in the Edit Events
dialog box. You cannot turn off front panel locking for filter events.

© National Instruments | 1-9

Lesson 1 Moving Beyond Dataflow

Static Event Registration

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.

Configuring Events
Before you configure events for the Event structure to handle, refer to the Caveats and
Recommendations when Using Events in LabVIEW topic of the LabVIEW Help.

Complete the following steps to configure an Event structure case to handle an event.
1. (Optional) If you want to configure the Event structure to handle a user event, a Boolean control
within a radio buttons control, or a user interface event that is generated based on a reference
to an application, VI, or control, you first must dynamically register that event. Refer to the
Dynamically Registering Events topic of the LabVIEW Help for more information about using
dynamic events.
2. Right-click the border of the Event structure and select Edit Events Handled by This Case
from the shortcut menu to display the Edit Events dialog box to edit the current case. You also
can select Add Event Case from the shortcut menu to create a new case.
3. Specify an event source in the Event Sources pane.
4. Select the event you want to configure for the event source, such as Key Down, Timeout, or
Value Change from the Events list. When you select a dynamic event source from the Event
Sources list, the Events list displays that event. This is the same event you selected when you
registered the event. If you have registered for events dynamically and wired event reg refnum
out to the dynamic event terminal, the sources appear in the Dynamic section.
5. If you want to add additional events for the current case to handle, click the + button and repeat
steps 3 and 4 to specify each additional event. The Event Specifiers section at the top of the
dialog box lists all the events for the case to handle. When you click an item in this list, the
Event Sources section updates to highlight the event source you selected. You can repeat
steps 3 and 4 to redefine each event or click the X button to remove the selected event.

1-10 | ni.com
 LabVIEW Core 2 Course Manual

6. Click the OK button to save the configuration and close the dialog box. The event cases you
configured appear as selection options in the event selector label at the top of the Event
structure and the Event Data node displays the data common to all events handled in that case.
7. (Optional) You can use a Timeout event to configure an Event structure to wait a specified
amount of time for an event to occur. Wire a value to the Timeout terminal at the top left of the
Event structure to specify the number of milliseconds the Event structure should wait for an
event to occur before generating a Timeout event. The default value for the Timeout terminal
is –1, which specifies to wait indefinitely for an event to occur.
8. Repeat steps 1 through 6 for each event case you want to configure.

Notify and Filter Events

Notify events are an indication that a user action has already occurred, such as when the user has
changed the value of a control. Use notify events to respond to an event after it has occurred and
LabVIEW has processed it. You can configure any number of Event structures to respond to the
same notify event on a specific object. When the event occurs, LabVIEW sends a copy of the event
to each Event structure configured to handle the event in parallel.

Filter events inform you that the user has performed an action before LabVIEW processes it, which
allows you to customize how the program responds to interactions with the user interface. Use filter
events to participate in the handling of the event, possibly overriding the default behavior for the
event. In an Event structure case for a filter event, you can validate or change the event data before
LabVIEW finishes processing it, or you can discard the event entirely to prevent the change from
affecting the VI. For example, you can configure an Event structure to discard the Panel Close?
event, which prevents the user from interactively closing the front panel of the VI.

Filter events have names that end with a question mark, such as Panel Close?, to help you
distinguish them from notify events. Most filter events have an associated notify event of the same
name, but without the question mark, which LabVIEW generates after the filter event if no event
case discarded the event.

For example, you can use the Mouse Down? and Shortcut Menu Activation? filter events to display
a context menu when you left-click a control. To perform this action, modify the data returned by
the Button event data field of the Mouse Down? filter event. The value of the left mouse button is
1, and the value of the right mouse button is 2. In order to display the context menu when you
left-click a control, change the Button event data field to 2 so that LabVIEW treats a left-click like
a right-click.

As with notify events, you can configure any number of Event structures to respond to the same
filter event on a specific object. However, LabVIEW sends filter events sequentially to each Event
structure configured for the event. The order in which LabVIEW sends the event to each Event
structure depends on the order in which the events were registered. Each Event structure must
complete its event case for the event before LabVIEW can notify the next Event structure. If an
Event structure case changes any of the event data, LabVIEW passes the changed data to
subsequent Event structures in the chain. If an Event structure in the chain discards the event,
LabVIEW does not pass the event to any Event structures remaining in the chain. LabVIEW

© National Instruments | 1-11

Lesson 1 Moving Beyond Dataflow

completes processing the user action which triggered the event only after all configured Event
structures handle the event without discarding it.

Note National Instruments recommends you use filter events only when you want to
take part in the handling of the user action, either by discarding the event or by modifying
the event data. If you only want to know that the user performed a particular action, use
notify events.

Event structure cases that handle filter events have an Event Filter Node. You can change the event
data by wiring new values to these terminals. If you do not wire a value to the data item of the Event
Filter Node, the default value equals the value that the corresponding item in the Event Data Node
returns. You can completely discard an event by wiring a TRUE value to the Discard? terminal.

Note A single case in the Event structure cannot handle both notify and filter events.
A case can handle multiple notify events but can handle multiple filter events only if the
event data items are identical for all events.

Refer to the Using Events in LabVIEW section of this lesson for more information about event
registration.

Tip In the Edit Events dialog box, notify events are signified by a green arrow, and filter
events are signified by a red arrow.

Event Example
Figure 1-3 shows an Event structure configured with the Menu Selection (User) event. This VI uses
the Event structure to capture menu selections made using the user-defined menu named
sample.rtm. The ItemTag returns the menu item that was selected and the MenuRef returns the
refnum to the menubar. This information is passed to the Get Menu Item Info function. Refer to
examples\general\uievents.llb for more examples of using events.

Figure 1-3. Menu Selection (User) Event

Note If you use the Get Menu Selection function with an Event structure configured to
handle the same menu item, the Event structure takes precedence, and LabVIEW ignores
the Get Menu Selection function. In any given VI, use the Event structure or the Get
Menu Selection function to handle menu events, not both.

1-12 | ni.com