Numeric Input State Variable Reference

Related documents

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

Table of contents

• Introduction
• Constructor
• Instance methods
  • Inherited methods
• Instance properties
  • Inherited properties
  • fmt
  • max
  • min
  • isNumber
  • isUnit
  • unit
• Component attributes
  • Inherited attributes
  • numInputType
  • fmt
  • valueOnly
  • plusMinus
• DOM element properties

Introduction

Numeric Input state variables represent user number inputs. Each rendered component will display according to the format and limits specified in the state variable.

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.

If the state variable's ID contains a subName (e.g., 'myPage_mySv_kg'), it will be considered a unit specifier. If a rendered numeric input component has the showUnits attribute, the unit abbreviation for the unit subName will be displayed after the number.

Constructor

• Type string: 'numericInput', class: NumInputSv

Syntax

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

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.

  • fmt (optional)
    The fmt parameter can be one of the following:

    • A NumFmt instance specifying the desired numeric format and limits.
    • A NumFmt format string (fmtStr). If a format string is used, then a NumFmt instance will be created using this string along with any info.min and info.max parameters.

    if no fmt is provided, a format string of '8' is assumed.

  • 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. May be a function, in which case it is called (with no arguments) to supply the initial value; the function itself is kept as dflt. If omitted, info.min is used, and if that is also omitted, 0.

• onUserChange (optional)
  A function called by the component after the user enters a value. It receives the new, already clamped value. See onUserChange.

Note: If the info.id contains a subName (e.g., 'myPage_mySv_kg'), the first subName is stored in the unit property and isUnit is true. The unit is used only for display (see showUnits); unit conversion requires a unitInput state variable.

Instance methods

Inherited methods

• StateVar methods
• ModelValueSv methods
• InputSv methods

val([value])

Gets or sets the value. A NaN is converted to INVALID_NONE, and the value is passed through fmt.apply() (rounding to rndMult) before being stored.

userChange(value)

Called by the component with the value the user entered. A string has commas removed and is converted to a Number. A non-finite value is ignored with the notice "Invalid value. Ignoring." A value outside the fmt limits is clamped to the limits with the notice "Value outside limits. Adjusting." The clamped, rounded value is then stored and a sync is forced so the displayed input reflects the stored value.

isValid([value])

True if the InputSv test passes and fmt.isValid(value) (value within the format's limits).

fmtVal()

Returns the value formatted by fmt. Returns '-' if the value is outside the format's range, or the Error text if the value is an Error.

Note: The component() method returns a NumInputSvCmp.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties
• InputSv properties

fmt

A NumFmt instance specifies the desired numeric format and limits. The instance is held in the child state variable childSv.fmt (a modelObject). Assigning a new NumFmt replaces it, clamps the current value to the new limits and notifies monitors of the change, which causes mounted components to remount.

Value

A NumFmt instance.

max

The maximum valid value. Sets/gets fmt.max.

Value

A Number.

min

The minimum valid value. Sets/gets fmt.min.

Value

A Number.

isNumber

Always true for numericInput.

Value

A Boolean.

isUnit

True if the state variable has a unit subName.

Value

A Boolean.

unit

The first subName. For example, 'kg' if the state variable ID is 'myPage_mySv_kg'.

Value

A String.

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 the attribute is not specified, the current value of sv.set_numInputType is used (and the component remounts if it changes). 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 state variable's fmt for this component only.

valueOnly

If true, the component renders as a numericOutput component (display only).

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 state variable instance properties.
• The <input> element may be converted to <input type="text"> when it loses focus.
• The value attribute will be synchronized with the state variable value. The min, max and step attributes will be synchronized with respective properties in the NumFmt instance in the state variable'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.