Unit Input State Variable Reference

Related documents

• State Variables Overview
• StateVar Reference
• Built-in State Variables
• Input SV Type Reference
• Unit Output State Variable Reference

Table of contents

• Introduction
• Constructor
• Instance methods
  • Inherited methods
  • getSavedState()
  • setSavedState()
  • isValidState()
• Instance properties
  • Inherited properties
  • isNumber
  • isUnit
  • isUnitParent
  • unitClass
  • isDisabled
  • min, max, fmt
  • className
  • unitSiblings
• Component attributes
  • Inherited attributes
  • numInputType
  • fmt
  • plusMinus
• DOM element properties

Introduction

A unit input (unitInput) state variable represents a user numeric input value with multiple possible units. The app may provide the user a choice of their desired units for the number. The app can also choose which units it wants to compute with independent of the user's choice. Each rendered component will display according to the format and limits specified for the chosen unit in the state variable.

The unit input contains several child numericInput state variables, one for each unit is supports. Each child state variable is published with a subName corresponding to its unit (e.g., 'myPage_mySv_kg' and 'myPage_mySv_lb'). When one child state variable changes, the others are updated with the new value converted to their respective units.

Each unit input has an associated unitClass string. Each unitClass is associated with a unitSelector state variable. The unitSelector state variable controls which unit each rendered component will be displayed to the user. Many unitInput state variables can have the same unitClass, and, therefore will be controlled by the same unitSelector.

The unitInput state variable's component instance will display the currently selected unit sibling. If the showUnits attribute or the '{{...@}}' template syntax is used, the component will also display the appropriate unit abbreviations for the currently selected unit.

The app code or a component template may also refer to a specific child numericInput state variable. Any modification to that child will also update its siblings with converted values.

MVCS supports three types of numeric input mechanisms: a physical or virtual keyboard, a popup keypad, or a thumbwheel. The app Settings page can select the desired input mechanism for each device type by setting the sv.set_numInputType state variable. See Standard Settings Page.

Constructor

• Type string: 'unitInput', class: UnitInputSv

Syntax

ctl.createPage({
	...,
	stateVarInfo:[
		{type:'unitInput', ...},
	],
})

Parameters

• info
  An object containing the state variable properties. The info object can contain the following properties, but subclasses of StateVar may have additional properties:

  • StateVar info properties.
  • Model SV type info properties.
  • Input SV type info properties.
  • unitClass
    The unitClass string for the unitSelector that controls which unit sibling is current for this state variable.
  • units
    An object with one or more keys. Each key is a subName for a child state variable. The key value is a numeric input constructor info object. The first unit info object that supplies a max key is considered the primary unit sibling. If no child state variable supplies a max key, then the first key is considered primary. If a sibling does not declare a max or min value, then the max and/or min values from the primary sibling will be converted to the max and min values for that sibling.
  • dflt (optional)
    The default value in the primary unit, used only if the primary unit's info.units entry has no dflt of its own. Other siblings convert their defaults from the primary unit unless they supply their own dflt.

  The object for each unit has the following keys:

  • fmt
    A NumFmt format string (fmtStr). A NumFmt instance will be created using this string along with the unit's min and max (converted from the primary unit if not supplied). Only the primary unit may omit fmt (a format string of '8' is then assumed); every other unit must supply a format string. The primary unit may alternatively supply a NumFmt instance.
  • min (optional)
    The minimum valid value. This is ignored if a NumFmt instance is provided in the fmt parameter.
  • max (optional)
    The maximum valid value. This is ignored if a NumFmt instance is provided in the fmt parameter.
  • dflt (optional)
    The default value for this unit.

Instance methods

Inherited methods

• StateVar methods
• ModelValueSv methods
• InputSv methods

Note: The component() method is inherited from OutputSv and wraps render(). The parent's render() returns a <When> that renders a <StateVar> for the current unit sibling, and re-renders it when the unitSelector value changes. The component that is ultimately displayed is the current sibling's NumInputSvCmp, so the numericInput component attributes apply.

The following methods are shared with unitOutput and operate on the current unit sibling (curSv):

• val([value]), isValid(...), setDflt(), fmtVal(), fmtUnit(), and userChange(value).
• getUnitSv(unit)
  Returns the sibling state variable for unit. Asserts if there is none.
• siblings()
  Returns an array of all the unit sibling state variables.
• unitSiblingId(unit)
  Returns the ID of the sibling for unit (<id>_<unit>).

getSavedState()

Syntax

getSavedState()

Returns the state of the current unit sibling state variable. If the current sibling's value is not valid, its default is returned as the value.

Return value

Returns an object with the following keys:

• unit
  The subName for the current unit.
• value
  The value for the current unit sibling.

setSavedState()

Syntax

setSavedState(state)

Sets the state variable to the internal state specified by state. If state is not an object with a unit, or the unit is not one of this state variable's units, the state variable is set to its default (the latter is logged). If state.value is not valid, the sibling for that unit is set to its default.

Parameters

• state
  The state previously returned by getSavedState().

isValidState()

Syntax

isValidState(state)

Returns true if state is an object whose unit is one of this state variable's units and whose value is valid for that unit's sibling.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties
• InputSv properties

isNumber

Not set on the unitInput parent. It is true for each unit sibling numericInput.

Value

A Boolean.

isUnit

Always true for unitInput.

Value

A Boolean.

isUnitParent

Always true for unitInput.

Value

A Boolean.

unitClass

The unitClass string for the unitSelector that controls which unit sibling is current for this state variable.

Value

A String.

isDisabled

Gets the disabled state of the current unit sibling. Setting it sets the disabled state of every sibling, so the state holds whichever unit is displayed.

Value

A Boolean.

min, max, fmt

Getters that return the current unit sibling's min, max, and fmt. Setting any of them on the parent asserts (it fails); set them on a sibling instead. Setting min or max on a sibling converts and sets the limit on every sibling.

className

Gets/sets the className of the current sibling; setting applies to all siblings.

unitSiblings

A Map from unit to sibling state variable.

Component attributes

Inherited attributes

• Component attributes

numInputType

The numInputType attribute establishes a particular user input type that overrides the sv.set_numInputType state variable. If not specified, the current value of sv.set_numInputType is used. The values can be:

• 'keyboard'
  Use the standard physical or virtual keyboard.
• 'keypad'
  Use a popup numeric keypad.
• 'thumbwheel'
  Use a popup thumbwheel selector.

Value

A String.

fmt

A NumFmt instance or format string that overrides the current sibling's format for this component.

plusMinus

If plusMinus is true, then "-" and "+" buttons will apear to the left and right of the input. Pressing one of the buttons will increment or decrement the value by fmt.rndMult.

Value

A Boolean.

DOM element properties

• Standard DOM element properties
• For the keyboard numInputType, the numericInput Component will render an <input type="number"> with the value, max, min, and step attributes set according to the respective current numeric input state variable properties.
• The <input> element may be converted to <input type="text"> when it loses focus.
• The value attribute will be synchronized with the current unit sibling value. The min, max and step attributes will be synchronized with respective properties in the NumFmt instance in the current unit sibling's fmt property.
• The <input> element will have a className that contains 'svIo_numInput'.
• For a popup numInputType, the numericInput Component will render a <span>.
• The <span> contents will be synchronized with the state variable value.