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()
  • isType()
  • isValid()
  • isValidState()
  • isValue()
  • removeChangeListener()
  • setSavedState()
  • val()
• Instance properties
  • id
  • info
  • fieldValue
  • forcedGenCnt
  • isDisabled
  • isInput
  • isNumber
  • isParent
  • isOutput
  • isSelector
  • isUnitCtl
  • isUnitParent
  • log
  • page
  • name
  • subNames
  • 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 StateVar and for Output-type state variables.

  • parent
    The creating state variable, for non-public child state variables. Becomes the parent property.

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

    • sv
      The global sv namespace object (not the state variable being assigned).
    • newValue
      The assigned value for the state variable.
      The function may set a state variable value to whatever is required in response to the invalid value or generate a warning. The return value is ignored.

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 = false, changeFn = null)

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.
• changeFn
  Accepted but ignored by SvMonitor.

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.

isType()

Syntax

isType(type)

Returns true if the state variable is an instance of the class registered for the SV type string type (see SV.defineType()).

Parameters

• type
  An SV type string such as 'numericInput'.

Return value

A Boolean.

isValid()

Syntax

isValid(value = this._value)

Return true if value (by default the current state variable value) is considered valid. For StateVar this means not an Error; subclasses restrict this further.

Parameters

• value (optional)
  The value to be tested. Defaults to the current state variable value.

Return value

A Boolean. Returns true if the 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. The method always returns the current internal value (_value), whether or not an argument is given. If the new value is invalid and an onError function was supplied, it is called as onError(sv, value).

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 current state variable value. 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. It is stored in the private _info property; there is no public info getter.

Value

An object.

fieldValue

The most recent value assigned with val(), even if it was rejected as invalid or transformed. Input SVs use it to restore the displayed field contents (see getSavedState() in Input SV Type Reference).

Value

Any.

forcedGenCnt

A counter incremented by forceChange() (and by doChange() on object-type SVs). SvMonitor compares it to detect forced changes.

Value

A number.

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.

log

If truthy, each val(value) assignment logs the SV ID and value to the console. Not set by default; assign it from the console for debugging.

Value

A Boolean or undefined.

page

The page part of the ID, from stateVar.parseId().

Value

A string.

name

The name part of the ID.

Value

A string.

subNames

The remaining _-separated parts of the ID (for example the unit).

Value

An array of strings (empty if none).

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. Input-type state variables default to 'global', others to 'none'. 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 StateVar and for Output-type state variables.

Value

A string: 'none', 'local', or 'global'. Defaults to 'none'.

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.