MiceOnABeam Product Documentation

Modified: 12/23/2011 5:05 PM
Recently changed articles You can subscribe to this wiki article using an RSS feed reader.

Choice Point

Summary

A Choice Point provides the ability to merge one or more incoming transitions and then target one out of a set of outgoing transitions whose Guard Condition evaluates to TRUE.

Graphic

A Choice Point with name C1 is represented by the following graphic:

One or more incoming transitions can be connected to the top vertex of the diamond. Outgoing transitions are connected to the remaining three vertices, depending on the location of the destination component connected to by the outgoing transition. If the mid-point of the outgoing transition is ten pixels below the bottom vertex, then the transition connects to the bottom vertex. Otherwise if the transition mid-point is to the left of the center of the Choice Point then the transition connects to the left vertex. Similarly so for a component to the right of the Choice Point.

Description

The Choice Point is a decision node in the flow of program logic from one state to another.

When a script has received an event, often the specific state to transition to, is based on the value of some condition. Typically this is directly implemented in LSL via a construct of the form if (condition) {state x;} else if (condition2) {state y;} MiceOnABeam allows you to express this graphically via the Choice Point.

►In programming terms, the Choice Point is similar to a case or switch statement, however it's important to note that a Choice Point is NOT the graphical analog for every LSL if else if sequence of statements. It should ONLY be used when a decision has to be made as to which state to move to after receiving a particular event.

When a Choice Point is entered, each outgoing transition is examined in turn. If a transition's Guard Condition is evaluated to be TRUE, then that transition is considered fired, so it's path is followed, and no further outgoing transitions are examined.

If no outgoing transition's Guard Condition evaluates to TRUE, then a transition whose guard is set to ELSE is taken. If in such case no ELSE transition had been defined, then the model would be considered ill-defined, and the script terminated with the message, "Script terminated! No guard evaluates TRUE for Choice Point: C1 in state: StateName".

Usage

The following model has states S and S1 each capable of responding to a touch event. If the script is in either state and a touch event is received, then the state's corresponding touch transition is triggered, and it is followed to the Choice Point named C.

At this point transitions T and T1 are examined (see Notes), and the transition whose Guard Condition evaluates to TRUE, is taken. So if x==1, transition T is taken to state S2. If x==2, transition T1 is taken to state S3.

If x!=1 and x!=2, then the ELSE transition is taken to state S4.

Notes

  • Each Choice Point must be uniquely named within the context of a composite state.
  • A Choice Point can accept incoming/outgoing transitions to/from any valid transition source/destination respectively.
  • The order in which outgoing transitions are examined is not specified, but will be consistent for a particular model.
  • If a Choice Point has multiple incoming transitions each with their own event, Guard Condition & Transition Action code will not have direct access to the arguments of the originating event message. Instead, to access these arguments, one of the Event Data access functions EVENT_xxx("argument name") must be used, where argument_name is the name of the argument to be retrieved.  See LSL Events for a list of LSL events together with their named arguments.

In the case where the Choice Point has only a single incoming transition which has a defined event, the event argument names can be referenced directly within the Guard Condition or Transition Action of any outgoing transition.

Further, direct named access to the event arguments will be available in all outgoing transitions of any following single-input Choice Point connected to the original Choice Point with the single incoming event.

  • A transition whose Guard Condition is set to ELSE only has the "else" meaning when outgoing from a Choice Point. If an ELSE is used as the guard for a transition outgoing from any other modeling component, it is handled as if the guard was set to TRUE.
Tags:
Home: MiceOnABeam Product Documentation Copyright © 2010-2018 MiceOnABeam Software