Thumbwheel Reference

Table of contents

Introduction

MVCS provides a customizable popup thumbwheel input. The wheels can contain, numbers, string or other symbols in a flexible arrangment.

The thumbwheel is controlled using the thumbWheel object. The thumbWheel.open() method will open a custom thumbwheel, while the thumbWheel.number() method will open a numeric thumbwheel. Both methods return a Promise for receiving the results. The thumbWheel.open() method is the most flexible. It provides a custom wheel layout.

The thumbwheel is implemented as the overlay page twheel. The page has the state variables twheel_wheels (a modelObject holding the wheels array passed to thumbWheel.open()), twheel_resolve (a modelObject holding the resolve function of the returned Promise), and twheel_className (a modelValue that drives the show/hide slide animation, 'tw-show' or 'tw-hide'). The page is opened by thumbWheel.open() through nav.overlayPage('twheel', {wheels, resolve}). Applications should use the thumbWheel methods rather than opening the page directly.

Numeric thumbwheel format strings

The thumbWheel.number() method builds a set of thumbwheels from a given NumFmt object. By default, one wheel is provided for each possible integer and fractional digit in the format. You can customize this layout by including a thumbwheel numeric format string. The string can be used to group sets of digits or include special symbols. The string is specified by using 'T<string>' at the end of a NumFmt format string (fmtStr).

A ? in a format string represents a single-digit place in a formatted number. A format string of '?' would typically represent a single wheel with the digits 0 through 9. The actual digits may be limited by the format's min, max, or rndMult values. For example, if min was 1 and max was 5, only the digits 1 through 5 would be on the wheel. A format string of '??' would typically represent a single wheel with the digits 0 through 99, which also may be limited by other format values.

A | in a format string separates wheels, so '?|?' would typically represent two wheels, each with the digits 0 through 9. A '+' at the start of the string will display a '+' or '-' sign on the leftmost wheel as appropriate. A '+-|' at the start of the string produces a wheel with a '+' and '-' on the left side. Other characters or symbols are passed through to the wheel. For example:

thumbWheel.number(new NumFmt('-2T+?|?|&deg;C', -59, 59))

produces:

Rounding can limit the internal wheel values:

thumbWheel.number(new NumFmt('4m250T?,|???'))

If no format string is provided, then the thumbWheel.number() method will provide a wheel for each decimal or fractional digit. For example:

thumbWheel.number(new NumFmt('2.1'))

produces a wheel layout equivalent to a thumbwheel numeric format string of '?|?.|?'.

Exported identifiers

thumbWheel

Syntax

import {thumbWheel} from 'common/mvcs/export.js';

The thumbWheel object provides methods and properties to control the popup thumbwheel input. It is also assigned to the global/window object as window.thumbWheel.

thumbWheel methods

number()

Syntax

thumbWheel.number(numFmt, value, units)
thumbWheel.number(numFmt, value)
thumbWheel.number(numFmt)

Opens a numeric thumbwheel that can handle numbers specified by the numFmt argument. If the value argument is provided, it sets the initial value. Otherwise, the intial value is zero. If the units argument is provided, then it is used to display a unit abbreviation following the value.

The numFmt argument is a NumFmt object. Any specified thumbwheel format is retrieved from the twFmt property. In no thumbwheel format format is specified, then there will be a wheel for each integer and fractional digit.

The thumbWheel.number() method returns a Promise. The Promise is resolved with the final value. If the user cancels the data entry, the Promise is resolved with the original value (the Promise is never rejected).

Parameters

Return value

A Promise that is resolved with the selected number when the user dismisses the thumbwheel with "Done". If the user presses "Cancel", the Promise is resolved with the original value. The Promise is never rejected.

open()

Syntax

thumbWheel.open(wheels)

Open a custom thumbwheel input. The wheels argument is an array that specifies the layout of each wheel. Each entry is an object that contains an array of strings representing the selectable items in each wheel. The thumbWheel.open() method returns a Promise that resolves to an array of the texts of the selected items. If a thumbwheel is already open, the call does nothing and returns undefined.

Parameters

Return value

A Promise that is resolved with an array containing the selected text string of each wheel when the user dismisses the thumbwheel with "Done". If the user presses "Cancel", the Promise is resolved with null. The Promise is never rejected.

select()

Syntax

thumbWheel.select(options, value)

Opens a single-wheel selector. This can be used in place of the usual dropdown selector when it is easier. The options argument defines the selectable options, and the value argument represents the initially selected option value.

Parameters

Return value

A Promise that is resolved when the user dismisses the thumbwheel. On "Done" it is resolved with the text of the selected item (selections[0] from open()); note that this is the item's displayed text, not its value, so the two are the same only for string elements. On "Cancel" it is resolved with the original value. The Promise is never rejected.

check()

Syntax

thumbWheel.check(id, numFmt, wheelFmt)

A debugging aid that asserts that a thumbwheel format string agrees with a number format string. The digits counts of the integer and fractional parts of numFmt must equal the numbers of ? characters in the integer and fractional parts of wheelFmt, otherwise an assertion with the message "Bad tw for id: <id>" is raised.

Parameters

Return value

undefined.