List Widget (List.class)

Use the List Widget to create a list of selectable text objects that share a common function (or set of functions) and that are vertically aligned in a box. Selecting a list object highlights that object on the display and invokes the href function(s) with the value of the list item being the argument. The values associated with each list entry are specified similar to C's "enum" specifier, where the first object in the list will have a value of 00, the second item 01, etc, unless an explicit value is given. If not all values are specified, unspecified values continue the progression from the last specified value. By specifying an initial condition, that option is highlighted when the page is loaded, the href function(s) are invoked and the value associated with that list object is used as the argument.

Important note: The HEIGHT and WIDTH attributes for List.class DO NOT specify the actual size of the List Box drawn on the screen. Instead, these attributes specify the size of the cell that contains the list box, and the relative position of other objects on the screen. The Gem code draws the box starting from the top-left corner of the cell. The code optimizes the width of the drawn box based on the width of the option titles and the specified font. The maximum number of visible list items that can fit in a box based on the HEIGHT attribute determines the actual height of the drawn box. Any remaining list items will be hidden from view, but are reachable via an arrow that allows for page scrolling through a list. You can also scroll through the list an item at a time by keeping the pen down and moving above or below the drawn list box.

List Parameter Attributes:

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

Parameter="fillColor" value= See color entry conventions — Specifies the desired list 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 fill is fully opaque.

Parameter="font" value="font, font size" — Specifies the font used for the option names within the list box. See Amulet GEM Font Converter for more information regarding the creation of .auf font files. Default is Bitstream Vera Sans. Default font size is 12pt.

Parameter="fontColor" value= See color entry conventions — Specifies the desired 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 list box font. If BOLD or ITALIC is not selected, PLAIN is the default fontStyle. The available font styles are:

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

Parameter="href" value="function(s)" — The function (or multiple/sequenced functions) invoked when a list item is hit. See Appendix B for all available functions for the List widget.

Parameter="initialCondition" value="string" or "FromInitHref" — Specifies which option string is highlighted when the page is loaded. The value associated with the highlighted option string is the argument given to the href function(s). If "FromInitHref" is selected, the function specified by the InitHref attribute is called. Whichever option has the same intrinsic value as the returned value from the initHref function will be initially highlighted.

Parameter="options" value="see image below" — Specifies the list strings and their values. The value can be any number from 0 - 65535 (0x00 - 0xFFFF) or a STRING (which must be in single quotes (' '). (See note regarding Control Widget intrinsic values.) The first option displays at the top of the list and each subsequent option displays directly below the previous. To add more options, hit the plus button in the lower left.

Parameter="selectionColor" value= See color entry conventions — Specifies the color of the highlighted entry in the list box. See section on colors for more information. If no selection color is specified, the default color is black. If the alpha is FF, then the selectionColor is fully opaque.

Parameter="selectionFontColor" value= See color entry conventions — Specifies the color of the font within the highlighted entry in the list box. See section on colors for more information. If no selection color is specified, the default color is white.

Optional List Parameter Attributes:

Parameter="downArrow" value="image" — Specifies the "page down arrow" image to use when the list has more items than can be viewed. If this attribute is not present, then a default image, the Amulet logo, is used. (Images can be either .GIF, .JPG, or .PNG.)

Parameter="downArrowAlt" value="image" — Specifies the "page down arrow" image to use when the down arrow is selected. If this attribute is not present, then a default image, the Amulet logo, is used. (Images can be either .GIF, .JPG, or .PNG.)

Parameter="initHref" value="function" — Specifies the function called when the page is loaded. Use this attribute whenever FromInitHref is used as the initialCondition. The value returned from this function call will determine which option string starts out highlighted. The value should match the intrinsic value of one of the options strings. See Appendix B for all available functions.

Parameter="scrollRate" value="seconds" — Specifies the rate at which the list scrolls when selecting the area directly below or above the list box. The default scroll rate is .45 seconds. The range is 0.01 - 655.35.

Parameter="upArrow" value="image" — Specifies the "page up arrow" image to use when the list has more items than can be viewed. If this attribute is not present, then a default image, upArrow.gif, located in Amulet/Color/Configuration/Widgets/List/, is used. (Images can be either .GIF, .JPG, or .PNG.)

Parameter="upArrowAlt" value="image" — Specifies the "page up arrow" image to use when the up arrow is selected. If this attribute is not present, then a default image, upArrowAlt.gif, located in Amulet/Color/Configuration/Widgets/List/, is used. (Images can be either .GIF, .JPG, or .PNG.)

Parameter="borderColor" value=See color entry conventions — Specifies the color of the list box border. See section on colors for more information. If no selection color is specified, the default color is black. If the alpha is FF, then the border is fully opaque.