Unit Selector State Variable Reference

Related documents

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

Table of contents

• Introduction
• Child state variables
• Constructor
• Instance methods
  • Inherited methods
  • fmtUnit()
• Instance properties
  • Inherited properties
  • isUnitCtl
  • unitClass
• Static methods
  • UnitSelSv.currentUnit()
  • UnitSelSv.getUnitSelector()
  • UnitSelSv.convertCurrentUnits()
• Component attributes
  • Inherited attributes
• DOM element properties

Introduction

Unit Selector state variables represent an input that allows the user to select the units to be displayed by the unitInput and unitOuput state variables of the same unitClass.

Unit Selector state variables inherit from the SelectorInputSv and support a specific type of options. The option value is the internal unit (e.g. 'kg'), and the text is what the user should see (e.g. "kg." or "Kilograms"). The unit values must be from those defined in Units.

By default, the selector renders as a popup list of units for the user to select. The currently selected unit is highlighted. The selector can also render as a set of radio buttons by specifying the radio attribute. The radio buttons can be horizontal or vertical, and the text labels can be on either side for both orientations by specifying one of the following attributes:

• labelTop
  A horizontal orientation with the selection text above the radio buttons.
• labelRight
  A vertical orientation with the selection text to the right of the radio buttons.
• labelBottom (default)
  A horizontal orientation with the selection text below the radio buttons.
• labelLeft
  A vertical orientation with the selection text to the left of the radio buttons.

The options are not saved when a Unit Selector Input is saved to storage. Only the selector value is saved. It is expected that the app code will reestablish the current unit options and upgrade the saved values as required.

Child state variables

Selector Input state variables maintain a public child state variable that can be referred to using the subname options (e.g., myPage_myUnitSelector_options). The child state variable's value is an array of options objects containing the following properties:

• text
  The text to display for the option.
• value
  The value of the state variable if this option is selected.

The child state variable can be used to determine when the state variable options change (as opposed to the state variable value).

Constructor

• Type string: 'unitSelector', class: UnitSelSv

Syntax

ctl.createPage({
	...,
	stateVarInfo:[
		{
			type: 'unitSelector',
			options: [{value:<i>valueString</i>, text:<i>textString</i>}, ...]
		},
	],
});

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.
  • options (optional)
    An array of options. The options are presented to the user in the same order. Each element can contain a string, a number, or an object. If an element is an object, it can contain the following properties:
    • text (optional)
      The text to display for the option. If text is omitted, then value coerced to a string is used.
    • value (required)

      The value of the state variable if this option is selected.
    

  If an element is a number, the displayed text is the number coerced to a string, and the value is the element. If an element is a string, it is used for both the displayed text and value.

Instance methods

Inherited methods

• StateVar methods
• ModelValueSv methods
• InputSv methods
• SelectorInputSv methods

Note: The component() method returns a UnitSelSvComponent, a subclass of SelectorInputSvCmp. If the component has both the valueOnly and showUnits attributes, it renders only a <span> containing the unit abbreviation (fmtUnit()) of the current unit; otherwise it renders as a selector.

fmtUnit()

Syntax

fmtUnit()

Returns the unit abbreviation (units.fmtAbbrev) for the currently selected unit (the state variable value). See Units. The method takes no parameters.

Return value

A string containing the unit abbreviation.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties
• InputSv properties
• SelectorInputSv properties

isUnitCtl

Always true for unitSelector.

Value

A Boolean.

unitClass

The unitClass string for this selector.

Value

A String.

Static methods

UnitSelSv.currentUnit()

Syntax

UnitSelSv.currentUnit(unitClass);

Return the current unit value from the unitSelector associated with unitClass. Returns a unit option value. This is typically string (e.g., 'kg'). Throws a TypeError if no unitSelector exists for unitClass.

Parameters

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

Return value

An option value.

UnitSelSv.getUnitSelector()

Syntax

UnitSelSv.getUnitSelector(unitClass);

Return the unitSelector state variable that controls unitClass, or undefined if there is none.

Parameters

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

Return value

A UnitSelSv instance or undefined.

UnitSelSv.convertCurrentUnits()

Syntax

UnitSelSv.convertCurrentUnits(value, fromUnits, unitClass);

Return the value converted from fromUnits units to the units selected by the current value of the unitSelecotor state variable for the unitClass.

Parameters

• value
  The numeric value to be converted.
• fromUnits
  The unit values must be from those defined in Units.
• unitClass
  The unitClass string for a unitSelector.

Return value

A Number.

Component attributes

Inherited attributes

• Component attributes
• Selector attributes

DOM element properties

• Standard DOM element properties
• Selector properties