Function Button Widget (FunctionButton.class)

Function buttons are Amulet anchors that provide either a "spring-loaded" or a "toggle" button image, depending upon the button type, to invoke a function (or set of functions) when hit. By default, function button images appear to depress when touched. You can also setup the button image to "shade" when touched with the alpha color. By default, when hit, a button invokes a function (or set of functions). Optionally, function buttons can be set to auto-repeat while pressed. Initial delay and repeat frequency can both be customized.

Each button can have a user-defined label (text or numeric) within the button image. If the label is specified as "fromInitHref", the label will be based upon a string variable that is passed from the initHref function at run-time. The label text will automatically wrap if the string exceeds the width of the function button. User-defined wraps can be specified by entering "\n" at the point of the desired wrap.

Function buttons can also be set up to auto-repeat. When pressed, an auto-repeat button delays a user-defined amount of time then invokes a function (or set of functions) at a user-defined frequency while the button is still being pressed. As a side benefit of the auto-repeat functionality, a button can be created that will appear to invoke its function(s) immediately upon being pressed instead of waiting until the button is released. By setting the delay very small and the frequency at 0, the button will invoke its function(s) after the very short delay time and not repeat again.

NOTE: To display a literal \ symbol in the label, use a double backslash in the string (e.g. 25 \\ 5 would display 25 \ 5 in the button).

Function Button Parameter Attributes:

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

Parameter="buttonType" value="TOGGLE" or "SPRING-LOADED" — Specifies the action of the button when hit. TOGGLE causes the button to depress (or invert) on a pen down event and stay depressed on the ensuing pen up event. SPRING-LOADED causes the button to depress on a pen down event and return to its original state on the following pen up event. SPRING-LOADED is the default.

Parameter="onButtonPress" value="DEPRESS" or "ALPHA" — Specifies the look of the button during a pen down condition. DEPRESS gives the illusion of the button being pressed. ALPHA shades the image of the button with a transparent color defined by alphaColor. DEPRESS is the default.

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

Parameter="label" value="text" or "FromInitHref" — Specifies the text that appears inside the button. The button will NOT automatically re-size to fit the text. If there is enough vertical room, text will automatically wrap. Any text that will not fit within the confines of the button will be truncated. User-defined wraps can be specified by entering "\n" within the text at the spot you would like the wrap to occur. There is a maximum of 5 lines for a button label. The name field can be left blank; blank is the default. To have the label be dynamically entered at runtime by the server, enter FromInitHref. By default, the dynamic button label can be a maximum of 25 characters in length. To increase the maximum number of characters, put the desired number in parentheses after FromInitHref. For example, to have a dynamic label up to 50 characters long, use FromInitHref(50). The attribute initHref needs to be of the type Amulet:UART.label(x).value(). It will be called only once upon the loading of the page, with the string returned from the server becoming the button label. See note regarding the use of InternalRAM label variables as button labels.

Optional Function Button Parameter Attributes:

Parameter="borderColor" value= See color entry conventions — Specifies the desired button border color. See section on colors for more information. If no border color is specified, the default color is black.

Parameter="fillColor" value= See color entry conventions — Specifies the desired button fill color. See section on colors for more information. If no fill color is specified, the default color is the current background color.

Parameter="font" value="font, font size" — Specifies the font used for the button label. See Amulet GEM Font Converter for more information regarding the creation of .auf font files. Default is Bitstream Vera Sans. The font size for the button label defaults to 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 button label font. The available font styles are:

• Bold — The option text is bold. (i.e. text)
• Italic — The option text is italicized. (i.e. text)
• Plain — The option text is standard font. (i.e. text)

Parameter="alphaColor" value= See color entry conventions — If onButtonPress equals ALPHA, this attribute specifies the alpha color mask used to notify the user the Function Button has been depressed. See section on colors for more information. If no alphaColor is specified, the default color is a transparent gray. If the color specified does not have an alpha component, then it will be completely opaque, which will result in a colored rectangle appearing in place of the button while it is touched.

Parameter="executeOn" value= "HIT" or "RELEASE" or "BOTH" — Specifies when the href function is launched, either when the button is hit, when the button is released, or when the button is both hit and released. If nothing is specified, the default is to "RELEASE".

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

Parameter="initHref" value="function" — Specifies the function called when the page is loaded. Use this attribute only when FromInitHref is used as the label. The string value returned from the function call will be used as the button label. Only available function is of type Amulet:UART.label(x).value(). See note regarding the use of InternalRAM label variables as button labels.

Parameter="noSdram" value="CHECKED" or "UNCHECKED" — Specifies if the background of the Function Button is stored in SDRAM or not. If noSdram=CHECKED, then applying the disappear() IWC method could result in strange behavior. If the parameter is UNCHECKED, the button widget will allocate space in the SDRAM equivalent to the size of the button within the frame buffer. UNCHECKED is the default.

Parameter="repeatDelay" value="number" — Time to delay from when button is initially pressed until it starts to auto-repeat. Specified in seconds, with a single floating-point number. The range is 0.00 - 655.35.

Parameter="repeatRate" value="number" — The href function call frequency while button is being pressed, after the initial delay determined by repeatDelay. Specified in seconds, with a single floating-point number. The range is 0.00 - 655.35. 0.00 means do not repeat.

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