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()
• Static methods
  • UnitCtlSv.currentUnit()
  • UnitCtlSv.getUnitSelector()
  • UnitCtlSv.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 SelectorInputSvCmp.

fmtUnit()

Syntax

fmtUnit()

Returns a unit abbreviation appropriate to the value. See Units.

Parameters

• value
  The value of the unit option to be searched for.

Return value

A string containing the unit abbreviation.

Static methods

UnitCtlSv.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').

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.

UnitCtlSv.getUnitSelector()

Syntax

UnitSelSv.getUnitSelector(unitClass);

Return the unitSelector state variable that controls 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

UnitCtlSv.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