StateVar Reference

Related documents

• State Variables Overview
• Built-in State Variables
• Model SV Type Reference
• Input SV Type Reference
• Output SV Type Reference
• Controller Reference

Table of contents

• Introduction
• Constructor
• Instance methods
  • addChangeListener()
  • breakOn()
  • createMonitor()
  • doChange()
  • forceChange()
  • getSavedState()
  • isDifferent()
  • isValid()
  • isValidState()
  • isValue()
  • removeChangeListener()
  • setSavedState()
  • val()
• Instance properties
  • id
  • info
  • isDisabled
  • isInput
  • isNumber
  • isParent
  • isOutput
  • isSelector
  • isUnitCtl
  • isUnitParent
  • parent
  • save
  • childSv
  • value

Introduction

StateVar is the superclass for all state variables. Its primary function is to store a value. The value can be any JavaScript type, but subclasses can restrict this. Subclasses can have other internal state including child state variables. This state is manipulated by other properties and methods and/or by directly using the child state variables.

The StateVar class does not schedule Model execution or View synchronization when the value is changed, though subclasses can modify this behavior.

The StateVar class is associated with the SV type string 'value'.

Note: Most state variables used by the Model and View, are subclasses of StateVar and are created during page creation by ctl.pageCreate(). See Model SV Type Reference and (Controller Reference)[controller.md].

Constructor

Syntax

new StateVar(info)

Parameters

• info
  An object containing the state variable properties. The info object can contain the following properties. Other properties intended for subclasses are ignored by the StateVar constructor.

  • id (required)
    The state variable ID string.

  • value
    The state variable’s initial value. The JS type of the value is dependent on the SV type.

  • save
    The save property may take one of the following values:

    • 'global'
      Save the state variable state both locally and to the cloud. This is the default value for Input-type state variables.
    • 'local'
      Save the state variable state both locally and to the cloud. When cloud values are used to restore state variable state, the locally saved values
      override the cloud values.
    • 'none'
      Don't save the state variable state. This is the default value for Output-type state variables.

  • onError
    A function to be called when an invalid value is assigned. The function signature is fn(sVar, newValue):

    • sVar
      The current state variable.
    • newValue
      The proposed new value for the state variable.
      The function may set the state variable value to whatever is required in response to the invalid value or generate a warning.

Instance methods

addChangeListener()

Syntax

addChangeListener(callbackFn)

Adds a listener function to be called whenever the value of the state variable is considered changed.

Parameters

• callbackFn
  A function with the signature callbackFn(sVar). The function is called when the state variable value is considered to be changed. It takes a single argument:
  • sVar
    The state variable that has been changed.

breakOn()

Syntax

breakOn(type)

Causes a debugger breakpoint when the SV is assigned a value that meets the conditions associated with the type argument.

Parameters

• type
type may take one of the following values:
  • ''
    Cause no break.
  • 'change'
    Break when the value is changed (isDifferent()).
  • 'get'
    Break when the value is read.
  • 'invalid'
    Break when an invalid value is assigned.
  • 'set'
    Break when a value is assigned.

createMonitor()

Syntax

createMonitor(noInitialChange)

Returns an SvMonitor for this state variable. If noInitialChange is truthy, the first invocation of the hasChanged() method on the SVMonitor will return false. Otherwise, it will return true. StateVar subclasses can override this method to return different subclasses of SvMonitor with different behavior.

Parameters

• noInitialChange
  If thruthy, the first call to the hasChanged() method will return false. Otherwise it will return true.

Return value

An SvMonitor for this state variable.

doChange()

Syntax

doChange()

Do what’s required when a change happens. By default, it calls all the change listeners. This may be overridden in a subclass, for example, to call the Controller to execute the Model.

forceChange()

Syntax

forceChange()

Force a change to be recorded. Runs the change listeners and forces subsequent hasChanged() invocations on SvMonitors to return true.

getSavedState()

Syntax

getSavedState()

Returns the state variable state. This may or may not represent the entire state of the state variable. For example, the state variable's className is usually excluded.

Return value

The return value type depends on the SV type. Simple state variables may return their value as a primitive type. More complex types might return an object representing their full internal state, including any subSvs.

isDifferent()

Syntax

isDifferent(value)

Return true if value is different from the current state variable value. This method is used internally to determine when a state variable value is considered changed. By default, isDifferent() returns true if value is different from the internal value according to Object.is().

Parameters

• value
  A value to be compared to the current value of the state variable.

Return value

A Boolean. Returns true if value is considered different from the current state variable value and false otherwise.

isValid()

Syntax

isValid()

Return true if the current state variable value is considered valid.

Return value

A Boolean. Returns true if the current state variable value is considered valid and false otherwise.

isValidState()

Syntax

isValidState(state)

Returns true if calling setSavedState(state) would result in a valid value. This give the caller a means to validate previsouly saved state.

Parameters

• state
  A value previously obtained from getSavedState()

Return value

A Boolean. Returns true if setting the state variable according to state would result in a valid value and false otherwise.

isValue()

Syntax

isValue(value)

Return true if value is considered the same as the current state variable value. This is only used externally and is not necessarily the inverse of isDifferent().

Parameters

• value
  A value to be compared to the current value of the state variable.

Return value

A Boolean. Returns true if value is the same as the current state variable value and false otherwise.

removeChangeListener()

Syntax

removeChangeListener(callbackFn)

Removes a change listener function previously added by the addChangeListener() method.

Parameters

• callbackFn
  The function passed to the addChangeListener() method when the listener was set up.

setSavedState()

Syntax

setSavedState(state)

Set the internal state of the state variable. This may or may not represent the entire state of the state variable. For example, the state variable's className is usually excluded.

Parameters

• state
  A value previously obtained from getSavedState()

val()

Syntax

val()
val(value)

With no arguments, return the state variable value. The allowed type of the value varies with SV type. With a value argument, sets the state variable value. If any breakOn() criteria are satisfied, a debugger break is executed. If an assigned value is considered changed, then any change listener callback functions are executed. These are the function forms of the value getter/setter.

Parameters

• value (optional)
  The value to be set. The allowed type of the value varies with the SV type. It may also be a StateVarError instance.

Return value

The state variable value. Only returned when no argument is provided. The JavaScript type is appropriate for the state variable.

Instance properties

These properties are available in every SV type:

id

The state variable’s ID string from info.id. An ID is required for all Model state variables. Other SV types may have an ID for debugging purposes.

Value

A string of the form '<page>_<name>', '<page>_<name>_<subName>', or '<page>_<name>_<subName>_<subName>...'.

info

The info object passed to the constructor.

Value

An object.

isDisabled

True if the state variable is an instance of an Input SV type and is disabled.

Value

A Boolean or undefined.

isInput

True if the state variable is an instance of one of the Input SV types.

Value

A Boolean or undefined.

isNumber

True if the state variable is an instance of the numericInput or numericOutput SV types.

Value

A Boolean or undefined.

isParent

True if the state variable is the parent of a childSv.

Value

A Boolean or undefined.

isOutput

True if the state variable is an instance of one of the Output SV types.

Value

A Boolean or undefined.

isSelector

True if the state variable is an instance of one of the Selector Input SV types.

Value

A Boolean or undefined.

isUnitCtl

True if the state variable is an instance of the unitSelector SV type.

Value

A Boolean or undefined.

isUnitParent

True if the state variable is an instance of the unitInput or unitOutput SV types.

Value

A Boolean or undefined.

parent

If the state variable is created by another state variable for storing internal state, this points to the creating state variable.

Value

An state variable object or undefined.

save

The value of info.save. The save property may take one of the following values:

• 'global'
  Save the state variable state both locally and to the cloud. This is the default value for Input-type state variables.
• 'local'
  Save the state variable state both locally and to the cloud. When cloud values are used to restore state variable state, the locally saved values override the cloud values.
• 'local'
  Don't save the state variable state. This is the default value for Output-type state variables.

Value

An state variable object or undefined.

childSv

If an state variable creates other state variables for its internal state, the childSv object holds pointers to the created state variables with the state variable sub-name as the key.

Value

An object.

value

The main value of the state variable. The type of the value varies with SV type. Subclasses of StateVar may have other internal state that is manipulated by other properties and methods and/or stored in child state variables.

Value

A value appropriate for the SV type.