Numeric Field Widget (NumericField.class)

The Numeric Field Widget uses a byte (or word) returned from an href function call to display a mixture of static text and a live number. The string is input using the standard C printf format. The Numeric Field Widget can display in integer, hexadecimal, and floating-point formats. Like printf, the variable is entered using the % character. The first digit following the % specifies the number of character spaces allocated to the live numeric field (including a decimal point, and plus (+) or minus (-) symbols). You can also have static text preceding and following the live numeric field. For example, to create a numeric field that displays "Output = 2.25 Volts", the printf field would read: "Output = %5.2f Volts". In this example, "5" specifies the number of character spaces, ".2" specifies the number of digits to the right of the decimal, and "f" specifies floating-point numbers.

If the width of the numeric field widget is less than required, the string will be truncated. Make sure your dimensions are large enough to hold all your text and numbers.

Numeric Field Parameter Attributes:

Parameter="invisible" value="CHECKED" or "UNCHECKED" — Specifies if the Numeric Field is to start out invisible or not. If the attribute is not present, then by default the Numeric Field is visible. If the Numeric Field starts out invisible, the only way to make it visible again is via the IWC method reappear().

Parameter="border" value="number" — Specifies width, in pixels, of the border around the dimensions of the numeric field. Default is 0, meaning no border.

Parameter="borderColor" value= See color entry conventions — Specifies the desired Numeric Field border color. See section on colors for more information. If no border color is specified, the default color is black. Only applicable if border is set to something other than 0. If the alpha is FF, then the border is fully opaque.

Parameter="fillColor" value= See color entry conventions — Specifies the desired Numeric Field fill color. See section on colors for more information. If no fill color is specified, the default color is the current background color. If the alpha is FF, then the fillColor is fully opaque.

Parameter="font" value="font, font size" — Specifies the font and font size used for the static text defined in printf. See Amulet GEM Font Converter for more information regarding the creation of .auf font files. Default is Bitstream Vera Sans. The default font size for the static text is 12pt.

Parameter="fontColor" value= See color entry conventions — Specifies the desired static text font color. See section on colors for more information. If no font color is specified, the default color is black.

Parameter="fontStyle" value="PLAIN" or "BOLD" or "ITALIC" — Specifies the style associated with the font of the static text defined in printf. PLAIN overrides any other style. The available font styles are:

• PLAIN — The option text uses the standard font. (i.e. text)
• BOLD — The option text is bold. (i.e. text)
• ITALIC — The option text is italicized. (i.e. text)

Parameter="href" value="function" — The function called to retrieve the widget input. See Appendix B for all available functions for the Numeric Field Widget. The function is called at an update rate specified by the updateFreq attribute.

Parameter="horizontalAlign" value="LEFT" or "CENTER" or "RIGHT" — Specifies the horizontal alignment of the string associated with the printf attribute within the Numeric Field dimensions. Only one value is allowed; you cannot mix horizontal alignments. Default is LEFT.

Parameter="max" value="number" — Maximum value returned from the href function; must be greater than min. If the function returns a byte, the range is 1 - 255 (0x01 - 0xFF). If the function returns a word, the range is 1 - 65535 (0x01 - 0xFFFF).

Parameter="maxFld" value="number" — Specifies what the numeric field displays when the maximum value is returned from the href function call. When using hexadecimal, you must precede the minFld number with 0x. By default, the 0x will NOT be displayed unless the "#" flag is used in the printf field. The maxFld value does NOT have to be greater than the minFld value. Range is -65535 to 65535 when using integers and floating point numbers and 0 to 0xffff when using hex numbers. See note below regarding the span between minFld and maxFld.

Note regarding the span between minFld and maxFld: When using integers and floating point numbers, the value stored by the Amulet OS is a 16-bit number. When using a floating point number, the decimal point is removed and the digits to the right of the decimal point are concatenated with those to the left of the decimal point. So, 655.35 is stored as 65535 (the maximum 16-bit number). In addition, the span between minFld and maxFld is limited to a 16-bit number. For example if the min is -65535, then the largest max can be is 0 (which would result in a span of 65535). Therefore, even though -65535 is a valid min and 65535 is a valid max, the span is larger than a 16-bit number (causing an Amulet compiler error).

Parameter="min" value="number" — Minimum value returned from the href function; must be less than max. If the function returns a byte, the range is 0 - 254 (0x00 - 0xFE). If the function returns a word, the range is 0 - 65534 (0x00 - 0xFFFE).

Parameter="minFld" value="number" — Specifies what the numeric field displays when the minimum value is returned from the href function call. When using hexadecimal, you must precede the minFld number with 0x. By default, the 0x will NOT be displayed unless the "#" flag is used in the printf field. The minFld value does NOT have to be less than the maxFld value. (Negative slope is permissible.) Range is -65535 to 65535 when using integers and floating point numbers, and 0 to 0xffff when using hex numbers. See note regarding the span between minFld and maxFld.

Table 1. Numeric Field formatting examples using the right-justified default. (The implied ranges are arbitrary.)

Parameter="printf" value="text %format text" — Specifies the text and the formatted numeric field to be displayed (similar to the standard C program printf command). The Numeric Field Widget can display integer, hexadecimal, and floating-point numbers.

To display integers, the format is %ai, where "a" is the number of character spaces, and "i" specifies integers. With floating-point numbers, the format is %a.bf, where "a" is the total number of character spaces, "b" is the number of digits to the right of the decimal point, and "f" specifies floating-point numbers. With hexadecimal numbers, the format is %aX or %ax, where "a" is the number of character spaces, and "X" specifies that the hexadecimal digits will be upper case (A-F), while "x" specifies lower case (a-f).

NOTE: To display a % symbol in the numeric field, use %% (e.g. Duty Cycle(%%)=%5.2f will display Duty Cycle(%)=99.99).

There are also flags that change the numeric field format. Format flags are entered between the % and the character space specification. The flags are: "-", "+", "0", "#" and " ". The flags are defined, as follows:

• "-" — specifies that the numeric field is left-justified. (The default is right-justified.)
• "+" — specifies that positive numbers are preceded with a plus sign.
• "0" — specifies that a right-justified numeric field lead with zeroes. (The default is right-justified with leading spaces).
• "#"— specifies that displayed hexadecimal numbers are preceded with 0x.
• " " — a blank space specifies that a left-justified numeric field lead with a single space when displaying a positive number, and lead with a negative sign (-) when displaying a negative number.

Parameter="updateFreq" value ="number" — Specifies the href function call frequency (specified in seconds, with a single floating-point number). The range is 0.00 - 655.35. A value of 0.00 means update never.

Parameter="updateDelay" value ="number" — Specifies the delay time from when the page is loaded until the first href function call (specified in seconds, with a single floating-point number). The range is 0.00 - 655.35. If this number is not specified, then the delay time defaults to the value in updateFreq.

Parameter="verticalAlign" value="TOP" or "MIDDLE" or "BOTTOM" — Specifies the vertical alignment of the string associated with the printf attribute within the Numeric Field dimensions. Only one value is allowed; you cannot mix vertical alignments. Default is TOP.

Parameter="waitForInit" value="CHECKED" or "UNCHECKED" — Specifies if the Numeric Field will wait for valid data before being displayed on the LCD. If CHECKED, the Numeric Field will not display any dynamic numbers until the first packet of data is received. If UNCHECKED, or the attribute is not present, the Numeric Field starts out displaying the minimum value until the first packet of data is received.

Optional Numeric Field Parameter Attributes:

Parameter="colorInvert" value="REGION" or "STRING" or "NONE" — Specifies if the string is shown with alternate colors. If REGION selected, the fillColorAlt and fontColorAlt will be used instead of fillColor and fontColor. If STRING selected, only fontColorAlt will be used instead of fontColor. If NONE selected, String Field will use fillColor and fontColor. Only one value is allowed; you cannot mix color inversion properties. Default is NONE.

Parameter="fillColorAlt" value= See color entry conventions — Specifies the desired Numeric Field fill color if colorInvert set to REGION. See section on colors for more information. If no alternate fill color is specified, the default alternate fill color is the logical inverse of the current fillColor. If the alpha is FF, then the fillColorAlt is fully opaque.

Parameter="fontColorAlt" value= See color entry conventions — Specifies the desired font color if colorInvert set to either REGION or STRING. See section on colors for more information. If fontColorAlt is not specified, the default alternate font color is the logical inverse of the current fontColor.