MiceOnABeam Product Documentation

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

State Variables & Functions

Summary

State Variables and Functions declared within the scope of a state are only accessible from within that state and within all it's contained substates, and so on down to the leaf states of the nested state hierarchy.

User Interface

State Variables and Functions are declared using the specific editor provided for that purpose. Selecting the context menu item Edit State Variables and Functions over a blank area of a State Editor will bring up that editor for the enclosing state. Selecting the same menu item while clicking over a substate, will bring up the State Variables and Functions Editor for that state.

This editor consists of two main sections, where State Variables and State Functions are respectively defined.

A State Variable is defined by selected an unused row in the State Variables section, choosing a Type, the variable Name, any initialization code, Initial Value, that may be necessary, together with a Description or comment for the variable. The description will be included alongside the variable's declaration in the generated LSL code (non-optimized version). The Configure column should be left unchecked unless the state is a special configurable component.

►Note that both the "=" and the final ";" for the variable's declaration are built-in and should not be entered in.

►The initialization value, by default, will be assigned to the variable when the generated script is first started up. Due to LSL restrictions on global variables, these values may only be simple constants; no complex expressions are permitted.

As a result, entering in a complex LSL expression for a State Variable's initialization will flag a parsing error, unless the variable is otherwise configured via the State Variable Configure Options dialog to initialize during state entry.

A State Function is defined by selected an unused row in the State Functions section, choosing a return type, (this field should be left blank if no value is returned), the function name and any parameters for the function in terms of type/name pairs.

►Note that the parentheses for the parameters "(" and ")" are built-in and should not be entered in.
The parameters are validated when attempting to leave the field. Any errors must first be resolved in order to save the changes to the State Function.

A State Function also requires a Function Body where the LSL code for the function is placed.

Note that the outermost braces for the function body "{" and "}" are built-in and should not be entered in. The code will be parsed by the built-in Code Editor.

Operation
  • Moving a State Variable or Function:
    Individual rows can be reordered by clicking a State Variable or Function on it's row header and dragging it to another row to where it will be moved (inserted before).

  • Copying a State Variable or Function:
    By holding down the CTRL key, the row will be copied to the new location instead of being moved. If copying, remember to change the name of the new variable or function!

    Note that the new row copying feature is available in the Edit User LSL Actions and the State Variable Configured Choices data grids as well.

  • Move or Copy a State Variable or Function Between States:
    In addition you are not limited to moving or copying the row to the same data grid: You can move or copy a State Variable/Function to the State Variables/Functions editor of a different state!

Description

LSL supports the declaration and use of variables and functions at the global level, making them accessible by all code within the script. Variables can also be defined local to the scope of a code block, defined by braces, { ... }. However, LSL does not permit the declaration of variables and functions scoped to the state level.

Due to MiceOnABeam's support for hierarchical states, the issue of variable and function scoping becomes even more important in order to fully take advantage of modularizing the design and abstracting out lower-level implementation details.

To address this variables and functions can be defined for a state and are only accessible from within the scope of that state.

Definition: The scope of a state consists of the state and all it's contained substates, and so on down to the leaf states of the nested state hierarchy.

Name Overrides

A variable or function which has the same name as one defined within a higher-level enclosing state, will override the higher-level variable or function within the state's scope.

Name overrides should normally be avoided, however this capability becomes necessary when incorporating reusable component models within your design.

Usage

The following model has three states, the implicit top state StateVariableHierarchy (which is the name of the script itself), LevelB and LevelC. Each of these three states declares an extended variable varA, varB, and varC respectively. As well they each declare an extended state function fcnA, fcnB and fcnC respectively.

 TopState State

 

LevelB State

 

LevelC State

 

The following table illustrates the variables and functions that are visible within each scope:

 

  TopState LevelB LevelC
varA
fcnA
varB  
fcnB  
varC    
fcnC    

 

Notes

  • If you define a new State Variable or State Function with a name that is already defined within a higher enclosing state or a lower substate, a confirmation prompt will be given alerting you to this and asking whether you wish to proceed.

Tags:
Home: MiceOnABeam Product Documentation Copyright © 2010-2018 MiceOnABeam Software