Jump to content

Event structure: Difference between revisions

From LabVIEW Wiki
← Older edit
VisualWikitext
No edit summary
Eyesonvis (talk | contribs)
14 edits
Note the behavior of front panel locking with subpanels.
 
(46 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Behaviour ==
{{TOCright}}
LV BE (Before Events) had the panel and diagram behaving as asynchronously as possible WRT one another. A control periodically handled UI events from the user and dropped the value into its terminal. Independently, the diagram takes the current value when it is needed and does its work. There is no synchronization between when the UI event is handled, when the value in the terminal changes, and when the diagram reads it. It is often a very simple way of writing your code and mimics how most hardware works. So why do events?
{{LabVIEW Palette Object Information|palette=Functions Palette/Programming/Structures{{!}}Structures palette|palette2=Functions Palette/Programming/Dialog & User Interface/Events{{!}}Events palette|type=structure|icon=Events Palette - Event Structure.png}}
[[File:Event Structure - Components.png|thumb|Components of the Event Structure]]


The primary reason for the events feature is to allow synchronization between the UI and the diagram. First off, the diagram gets notification of a value change. It is guaranteed not to miss user changes or to burn up the CPU looking for them. In addition to the notification, the diagram gets a chance to respond, to affect the rest of the UI, before the rest of the user input is evaluated. Maybe this part needs an example.
An '''Event Structure''' is a primitive [[Functions Palette/Programming/Structures|structure]] that can have multiple [[Subdiagram|subdiagrams]] (also known as "Event cases"), one of which is selectively executed at runtime. The structure waits for an event to occur, or until the timeout elapsed. While it waits, it doesn't take up any CPU time. Events can be triggered by user input or programmatically by the software. If an event happens while another event is executing, the new event is put on the [[#The event queue|event queue]].


Lets look at polled radio buttons. In theory, your diagram code polls fast enough to see each change in the radio buttons so that it can make sure that the previous button is set to FALSE. But when the user is faster than the diagram and presses multiple buttons, what order did they press them in? There has to be a fixup step to break the tie and pop out all but one button to FALSE regardless of the order the user clicked them.
== Usage ==
=== The event queue ===


With events, when the user clicks on a button, the panel is locked and will not process the next user click until the diagram finishes. This allows the diagram to see the button changes one at a time in the same order as the user presses.
Each event structure has an event queue that is managed by LabVIEW. The event queue is processed sequentially by the event structure. It is possible to remove elements from the event queue, using the [[Functions Palette/Programming/Dialog & User Interface/Events/Flush Event Queue|Flush Event Queue]] function. It is not possible to change, destroy or otherwise access the event queue.


Another example, perhaps a better one, is a panel with three action buttons: Save, Acquire, and Quit. The order that the presses are responded to is important, so the polling diagram has to "guess" whether to Save and then Acquire or Acquire, then Save. The Event Structure knows the order and the code in it is synchronized with the UI allowing for a better, more friendly UI.
=== Event types ===


Getting back on topic, the event structure introduces the synchronization, but the downside is that as with all synchronization, it allows for deadlocks when not used in the right way. As already discovered, nesting event structures is almost never the right thing to do, at least not yet.
Events are categorized into dynamic and static events.


As noted earlier, it is possible to leave the Event Structures nested, but turn off the UI locking. This appears to solve the problem, but it isn't how I would do it. I think a much better solution is to combine the diagrams of two structures into one. The value change for hidden controls will not happen, but it doesn't hurt to have it in the list of things to watch for. Another option is to place them in parallel loops. This will let the first structure finish and go back to sleep.
==== Dynamic events ====
[[File:Event Structure - Dynamic Events - Dynamic Event Terminals.png|thumb|Dynamic Event Terminals on the Event Structure]]


== Usage Tips ==
Dynamic events must be registered at runtime using the [[Register For Events function|Register For Events]] node, connected to the event structure via the ''Dynamic Event Terminals''. The ''Dynamic Event Terminals'' are hidden by default and must be enabled via the right-click menu option '''Show Dynamic Event Terminals'''.
0. Read the LabVIEW Help on "Loops and Case Structures, Case Sequence and Event Structures, Event Structures, Caveats and Recommendations when Using Events in LabvIEW"


1. Only place a single event structure within a while loop. In reality the while loop and the event structure are intimately linked so there should only ever be one event structure per loop.
Registered dynamic events are available in the [[#Edit events|configuration dialog]] under [[#Event sources|event sources]] >> [[#Dynamic|Dynamic]].


2. Never place an event structure within an event structure. It is better to solve issues where you might want to do this with some thought and perhaps a second while loop in parallel.
==== Static events ====


3. It is possible to have more than one event structure while loop combination on the same block diagram. There are valid reasons why you might want to do this: eg to have some events handled without pausing the while loop (Lock Panel Until Handler Completes = False) and others to wait until the handler completes (= True). The advice here is to separate out those events that lock the handler and those that do not lock the handler into separate while loops.
Static events are automatically added to the list of available [[#Event sources|event sources]] and do not have to be registered dynamically. They are generated for the current application, the current VI, panes on the front panel, splitters and controls. Static events are further separated into [[#Notify events|notify events]] and [[#Filter events|filter events]].


4. Whether the panel is locked until the handler completes is set individually for EACH case in the event structure.
===== [[File:Event Structure - Notify Event.png|frameless|border|Notify event]] Notify events =====


5. It is advisable to notify the user (ie with a message popup or mouse busy) when tasks that lock the panel take a long time to execute (> 0.5 s). Another way is to set some busy status message visible as the first step and then hide this message when the case exits.
Notify events handle a specific event. They are represented in the [[#Edit events|configuration dialog]] by a green arrow: [[File:Event Structure - Notify Event.png|frameless|border|Notify event]]


6. Boolean switches and their state require some thought when used within the event structure. With the default button style ("latch when released") LabVIEW reads the state of the boolean and only after reading does the button change back to it's other state. If the boolean is the "switched" type then TWO events are generated when the boolean is switched (ie F->T and T->F). If a single case of the event structure is used for "value chaged" on a boolean that is of the "switched" type, make sure that the code is only executed when the true event is processed (ie with a true/false case selector). This is most relevant where to use a boolean as a local variable then the boolean type must be of the "switched" type.
===== [[File:Event Structure - Filter Event.png|frameless|border|Filter event]] Filter events =====


== Why doesn't the event structure register local variable changes? ==
[[File:Event Structure - Event Filter Node.png|thumb|Event Filter Node on the Event Structure]]
The main reason for not sending events for programmatic value changes is to avoid feedback.


A happens. In responding to A, you update B and C. If responding to B or C results in changing A, then you have feedback and your code will behave like a dog chasing its tail. Sometimes the feedback will die out because the value set will match what is already there, but often it will continue indefinitely in a new type of infinite loop.
Filter events are executed '''before''' the actual event happens and have an additional '''filter node''' on the subdiagram. The '''filter node''' makes it possible to dynamically ''filter'' (and in some cases even ''alter'') notify events. Filter events are represented in the [[#Edit events|configuration dialog]] by a red arrow: [[File:Event Structure - Filter Event.png|frameless|border|Filter event]]


One solution to this is what is called User Events. You define what data they carry and when they fire. Then you either have the value change and the set local both fire the user event, or you can combine the event diagram to handle both and just fire the event when writing to the locals. Today, you can accomplish this with the queued state machine using the state machine to do all the common work and just having the event structure pass things to the queue.
=== Timeout behavior ===


== Locking The Panel ==
The timeout terminal on the event structure allows to execute the '''Timeout''' event if no other event has been executed for a certain amount of time. The event structure waits indefinitely if no value is connected to the timeout terminal or if the value is set to a value less than zero. If the timeout is set to a value greater than or equal to zero, the '''Timeout''' event is executed if no other event is executed within the specified period.
Given the synchronized mechanism of events, it is pretty easy to repost events to another queue or turn off locking and synchronization. If the event structure isn't synchronized, it would be impossible for the diagram to add it and become synchronized with the UI, so it is at least necessary for event diagrams to be able to lock the panel.


Should it be the default?
=== Edit events ===


In our opinion, yes. When responding to an event, it is pretty common to enable/disable or show/hide some other part of the display. Until you finish doing this, it is wrong for LV to process user clicks on those controls, and LV doesn't know which controls you are changing until you are finished.
[[File:Event Structure - Edit Events Dialog.png|thumb|Configuration dialog for event structures (Edit Events)]]


Additionally, it isn't the best idea, but what happens when the event handler does something expensive like write lots of stuff to a database inside the event structure? If the UI is locked, then the user's events don't do much, ideally the mouse is made to spin and this works the same as a C program. The user is waiting for the computer, and the UI more or less tells the user to be patient.
Events can be configured via the right-click menu options:


If the UI isn't locked, the user can change other things, but you can't execute another frame of your event structure until this one is finished. This is a node. It must finish and propagate data before it can run again, and the loop it is probably in can't go to the next iteration until it completes. You would have low level clicks being interpretted with the current state of the controls before the diagram has a chance to respond. This is sometimes the case, so it is possible to turn off event handling on the cases where you know that you may take awhile and you do not affect the state of the UI.
{| class="wikitable"
! Option
! Description
|-
| <tt>Edit Events Handled by This Case...</tt>
| Opens the configuration dialog for the current event case.
|-
| <tt>Add Event Case...</tt>
| Adds a new event case to the structure and opens the configuration dialog.
|-
| <tt>Duplicate Event Case...</tt>
| Makes a copy of the currently selected event in a new event case and opens the configuration dialog.
|-
| <tt>Delete This Event Case</tt>
| Deletes the currently selected event case.
|}


If you need to respond to the events in parallel, you can make a parallel loop, add an event handler for the other controls, and handle them there while this one churns away. That will work fine and it is IMO clear from the diagram what is synchronized and what is parallel. Taken to an extreme, each control has its own loop and this approach stinks, but it is a valid architecture. Note that for this to work well, you need to turn off the UI lock or have a node to release it.
The dialog is split into three columns: [[#Event specifiers|Event specifiers]], [[#Event sources|event sources]] and [[#Events|events]].


Another way of doing expensive tasks is to have the Event Structure do the minimum amount necessary before unlocking -- treat them like interrupts. Have the event structure repost expensive operations to a parallel loop or fire up an asynchronous dynamic VI. Now your event structure is free to handle events, your UI is live, LV is still a nice parallel-friendly language, and your diagram just needs to keep track of what parallel tasks it has going on.
=== Event specifiers ===


In the end, I'm not sure I can convince you, but if you continue to experiment with the different architectures that can be built using the Event Structure, I think you will come to agree that it normally doesn't matter whether it is locked or not. There are times where it is really nice that it is locked, and occasionally you may turn off locking so that the user can do additional UI things up to the point where synchronization is necessary again. For correctness, we decided that locking should be the default.
[[File:Event Structure - Edit Events Dialog - Event Specifiers.png|thumb|Event specifiers]]


I'd suggest reading the article on devzone sooner or later. It is in the Developer Insights/LabVIEW Guru section, and it will help start you down the right path.
Lists the event sources and events for the current event case. Each event case can have one or more unique event specifiers. The VI breaks if the same event specifier is used multiple times for the same or different event cases. The '''Add Event''' and '''Remove''' buttons can be used to add or remove events from the list of event specifiers.
 
=== Event sources ===
 
[[File:Event Structure - Edit Events Dialog - Event Sources.png|thumb|Event sources]]
 
Lists the event sources for the current VI. Categories in angle brackets are fixed and always available for all VIs. Grayed-out categories have no event sources.
 
{| class="wikitable"
! Event source
! Description
|-
| <tt>&lt;Application&gt;<tt>
| Events for the current application instance (executable)
|-
| <tt>&lt;This VI&gt;<tt>
| Events for the current VI
|-
| <tt>Dynamic</tt>
| Contains dynamic events registered by the [[#Dynamic events|dynamic events terminal]]
|-
| <tt>Panes</tt>
| Contains entries for [[Subpanel|panels]] on the front panel (by default only "Pane")
|-
| <tt>Splitters</tt>
| Contains entries for [[Splitter|splitters]] on the front panel of the current VI
|-
| <tt>Controls</tt>
| Contains the controls and indicators on the front panel of the current VI. [[Cluster|Clusters]] are nested by their containing controls and indicators.
|}
 
=== Events ===
 
[[File:Event Structure - Edit Events Dialog - Events.png|thumb|Events for '''Application''' event source]]
Lists [[#Notify events|notify]] and [[#Filter events|filter]] events for the currently selected event source. The ''filter'' box can be used to search for specific events. The description for each event is available in the [[Help window|help window]] while hovering over an entry in the list.
 
<br clear="all">
 
=== Lock panel (defer processing of user actions) until the event case completes ===
 
{| class="wikitable"
! Status
! Description
|-
| style="text-align: center;" | [[File:Checkbox Checked.png|frameless|border|Checked]]
| The front panel is unresponsive to user input while the event case executes.
|-
| style="text-align: center;" | [[File:Checkbox Unchecked.png|frameless|border|Unchecked]]
| The front panel stays responsive to user input while the event case executes.
|}
 
This checkbox is ''checked'' by default. When unchecked, any additional events are put on the event queue '''after''' the current event finished executing.
 
When an event case locks the panel, if the object that generates the event is in a subpanel, then LabVIEW locks the front panel that displays the subpanel.
 
=== Limit maximum instances of this event in event queue ===
 
{| class="wikitable"
! Status
! Description
|-
| style="text-align: center;" | [[File:Checkbox Checked.png|frameless|border|Checked]]
| The maximum number of events in the event queue for the current event case is limited to the specified number of '''instances'''.
|-
| style="text-align: center;" | [[File:Checkbox Unchecked.png|frameless|border|Unchecked]]
| The number of events in the event queue is unlimited.
|}
 
This checkbox is ''unchecked'' by default. When checked, the maximum number of events for the current event case can be defined in the '''Instances''' control below the checkbox.
 
The limit can only be specified if "[[#Lock panel (defer processing of user actions) until the event case completes|Lock panel (defer processing of user actions) until the event case completes]]" is ''unchecked'' (automatically unchecked by LabVIEW).
 
== Best practice ==
 
* Use the [[Producer/Consumer]] [[:Category:Design patterns|design pattern]] to execute time-consuming tasks outside event structures. This will keep the [[Wikipedia:User interface|user interface]] responsive.
* Use [[Functions Palette/Programming/Dialog & User Interface/Cursor/Set Busy|Set Busy]] and [[Functions Palette/Programming/Dialog & User Interface/Cursor/Unset Busy|Unset Busy]] when executing long-running events to give the user a visual feedback.
* Use only one event structure in a [[Functions Palette/Programming/Structures/While Loop|while loop]].
* '''Never''' handle the same event in multiple event structures.
* '''Never''' place an event structure within another event structure.
 
== FAQ ==
 
=== Why doesn't the event structure register local variable changes? ===
 
This is a design choice. Local variables are often used inside an event structure to update values on the front panel. If an event updates the value of the same control that generated the event, it would result in an infinite loop if the event is also generated for local variables. To programmatically generate events for controls use a [[Property node|property node]] for the '''Value (Signaling)''' property.<ref>https://knowledge.ni.com/KnowledgeArticleDetails?id=kA00Z0000019N6xSAE</ref>
 
== History ==
 
{| class="wikitable"
! Version
! Change(s)
|-
| [[File:LV8-2013.png|frameless|border|64x64px|LabVIEW 2013|link=LabVIEW 2013]]
| In [[LabVIEW 2013]] unhandled, dynamically registered events do not reset the timeout. Previously, if a dynamic event was registered but there was not an event case in the structure for the event, if the event fired the timeout would still be reset.  In [[LabVIEW 2013]] and later if there is not an event case in the structure for the event even if registered then it will not cause the timeout to reset.
|-
| [[File:LV8-2013.png|frameless|border|64x64px|LabVIEW 2011|link=LabVIEW 2011]]
| In [[LabVIEW 2011]] The Value Change is the default event when you define a new event case for a control or indicator.
|-
| [[File:LV7.png|frameless|border|64x64px|LabVIEW 6.1|link=LabVIEW 6i]]
| The Event Structure was added in [[LabVIEW 6i]]. Prior to this version, Event-Driven Programming was not supported.
|}
 
== See also ==
* [[EventStructure class]]
* [[User events]]
* [[Event Inspector Window]]
* [[Functions Palette/Programming/Dialog & User Interface/Events|Events Palette]]
* [[Producer/Consumer]]
 
== External links ==
 
* [http://www.ni.com/tutorial/3331 National Instruments: Event-Driven Programming in LabVIEW]
* [https://zone.ni.com/reference/en-XX/help/371361R-01/lvhowto/caveatsrecmndtnsevnts/ National Instruments: Caveats and Recommendations when Using Events in LabVIEW]
 
== References ==
<references />
 
[[Category:User interface]]
[[Category:Structures Palette]]
[[Category:Event Structure]]
[[Category:Event-Driven Programming]]
[[Category:Events Palette]]

Latest revision as of 19:37, 17 October 2022

Object information
Owning palette(s) Structures palette | Events palette
Type Structure
Requires Basic Development Environment
Icon
Components of the Event Structure

An Event Structure is a primitive structure that can have multiple subdiagrams (also known as "Event cases"), one of which is selectively executed at runtime. The structure waits for an event to occur, or until the timeout elapsed. While it waits, it doesn't take up any CPU time. Events can be triggered by user input or programmatically by the software. If an event happens while another event is executing, the new event is put on the event queue.

Usage

The event queue

Each event structure has an event queue that is managed by LabVIEW. The event queue is processed sequentially by the event structure. It is possible to remove elements from the event queue, using the Flush Event Queue function. It is not possible to change, destroy or otherwise access the event queue.

Event types

Events are categorized into dynamic and static events.

Dynamic events

Dynamic Event Terminals on the Event Structure

Dynamic events must be registered at runtime using the Register For Events node, connected to the event structure via the Dynamic Event Terminals. The Dynamic Event Terminals are hidden by default and must be enabled via the right-click menu option Show Dynamic Event Terminals.

Registered dynamic events are available in the configuration dialog under event sources >> Dynamic.

Static events

Static events are automatically added to the list of available event sources and do not have to be registered dynamically. They are generated for the current application, the current VI, panes on the front panel, splitters and controls. Static events are further separated into notify events and filter events.

Notify event Notify events

Notify events handle a specific event. They are represented in the configuration dialog by a green arrow: Notify event

Filter event Filter events
Event Filter Node on the Event Structure

Filter events are executed before the actual event happens and have an additional filter node on the subdiagram. The filter node makes it possible to dynamically filter (and in some cases even alter) notify events. Filter events are represented in the configuration dialog by a red arrow: Filter event

Timeout behavior

The timeout terminal on the event structure allows to execute the Timeout event if no other event has been executed for a certain amount of time. The event structure waits indefinitely if no value is connected to the timeout terminal or if the value is set to a value less than zero. If the timeout is set to a value greater than or equal to zero, the Timeout event is executed if no other event is executed within the specified period.

Edit events

Configuration dialog for event structures (Edit Events)

Events can be configured via the right-click menu options:

Option Description
Edit Events Handled by This Case... Opens the configuration dialog for the current event case.
Add Event Case... Adds a new event case to the structure and opens the configuration dialog.
Duplicate Event Case... Makes a copy of the currently selected event in a new event case and opens the configuration dialog.
Delete This Event Case Deletes the currently selected event case.

The dialog is split into three columns: Event specifiers, event sources and events.

Event specifiers

Event specifiers

Lists the event sources and events for the current event case. Each event case can have one or more unique event specifiers. The VI breaks if the same event specifier is used multiple times for the same or different event cases. The Add Event and Remove buttons can be used to add or remove events from the list of event specifiers.

Event sources

Event sources

Lists the event sources for the current VI. Categories in angle brackets are fixed and always available for all VIs. Grayed-out categories have no event sources.

Event source Description
<Application> Events for the current application instance (executable)
<This VI> Events for the current VI
Dynamic Contains dynamic events registered by the dynamic events terminal
Panes Contains entries for panels on the front panel (by default only "Pane")
Splitters Contains entries for splitters on the front panel of the current VI
Controls Contains the controls and indicators on the front panel of the current VI. Clusters are nested by their containing controls and indicators.

Events

Events for Application event source

Lists notify and filter events for the currently selected event source. The filter box can be used to search for specific events. The description for each event is available in the help window while hovering over an entry in the list.


Lock panel (defer processing of user actions) until the event case completes

Status Description
Checked The front panel is unresponsive to user input while the event case executes.
Unchecked The front panel stays responsive to user input while the event case executes.

This checkbox is checked by default. When unchecked, any additional events are put on the event queue after the current event finished executing.

When an event case locks the panel, if the object that generates the event is in a subpanel, then LabVIEW locks the front panel that displays the subpanel.

Limit maximum instances of this event in event queue

Status Description
Checked The maximum number of events in the event queue for the current event case is limited to the specified number of instances.
Unchecked The number of events in the event queue is unlimited.

This checkbox is unchecked by default. When checked, the maximum number of events for the current event case can be defined in the Instances control below the checkbox.

The limit can only be specified if "Lock panel (defer processing of user actions) until the event case completes" is unchecked (automatically unchecked by LabVIEW).

Best practice

  • Use the Producer/Consumer design pattern to execute time-consuming tasks outside event structures. This will keep the user interface responsive.
  • Use Set Busy and Unset Busy when executing long-running events to give the user a visual feedback.
  • Use only one event structure in a while loop.
  • Never handle the same event in multiple event structures.
  • Never place an event structure within another event structure.

FAQ

Why doesn't the event structure register local variable changes?

This is a design choice. Local variables are often used inside an event structure to update values on the front panel. If an event updates the value of the same control that generated the event, it would result in an infinite loop if the event is also generated for local variables. To programmatically generate events for controls use a property node for the Value (Signaling) property.[1]

History

Version Change(s)
LabVIEW 2013 In LabVIEW 2013 unhandled, dynamically registered events do not reset the timeout. Previously, if a dynamic event was registered but there was not an event case in the structure for the event, if the event fired the timeout would still be reset. In LabVIEW 2013 and later if there is not an event case in the structure for the event even if registered then it will not cause the timeout to reset.
LabVIEW 2011 In LabVIEW 2011 The Value Change is the default event when you define a new event case for a control or indicator.
LabVIEW 6.1 The Event Structure was added in LabVIEW 6i. Prior to this version, Event-Driven Programming was not supported.

See also

External links

References

  1. ↑ https://knowledge.ni.com/KnowledgeArticleDetails?id=kA00Z0000019N6xSAE
Retrieved from "https://labviewwiki.org/w/index.php?title=Event_structure&oldid=31863"