Custom Button Widget (CustomButton.class)

The Custom Button Widget uses two images (a pressed and a not pressed) to create a custom button. Custom buttons are Amulet anchors that allow a separate pressed image to appear instead of merely inverting the image. Custom buttons can be set to be either a "spring-loaded" or a "toggle" button. By default, when hit, a custom button invokes a function (or set of functions). Optionally, custom buttons can be set to auto-repeat while pressed. Initial delay and repeat frequency can both be customized.

Each custom 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 custom button. User-defined wraps can be specified by entering "\n" at the point of the desired wrap.

Custom 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. To create an instant hit button, set 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 within the button).

Custom Button Parameter Attributes:

Parameter="invisible" value="CHECKED" or "UNCHECKED" — Specifies if the Custom Button is to start out invisible or not. If the attribute is not CHECKED, then by default the Custom Button is visible. If the Custom 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="downImage" value="image" — Image used when custom button is pressed. Image file must be of type .GIF, .JPG, or .PNG.

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

• PLAIN — The option text is 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(s)" — The function (or multiple/sequenced functions) invoked when the button is hit. See Appendix B for all available functions for the Custom Button widget.

Parameter="onButtonPress" value="ALPHA" or "CUSTOM" or "DEPRESS" — Specifies the look of the button during a pen down condition. CUSTOM causes the downImage to appear and label text, if any, to shift down and to the right to give the illusion of being pressed. ALPHA blends a transparent color specified by alphaColor with the upImage and prohibits the downImage from appearing. DEPRESS gives the illusion of the button being pressed using only the upImage and the downImage will not appear. CUSTOM is the default.

Parameter="upImage" value="image" — Image used when custom button is not pressed. Image file must be of type .GIF, .JPG, or .PNG.

Parameter="cacheImage" value="CHECKED or UNCHECKED" — A checkbox that specifies to GEMstudio to store this image in the SDRAM in an uncompressed format for immediate use. Since the image is written to the SDRAM only once per project, it is not suitable for images that contain transparencies. (Images can be either .GIF, .JPG, or .PNG.)

Optional Custom Button Parameter Attributes:

Parameter="alphaColor" value= See color entry conventions — If onButtonPress equals ALPHA, this attribute specifies the alpha color mask used to notify the user the Custom Button has been depressed. See section on colors for more information. If no alpha color 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 Custom 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. Only available function is of type Amulet:UART.label(x).value(). See note regarding the use of InternalRAM label variables as button labels.

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.

Parameter="noSdram" value="CHECKED" or "UNCHECKED" — Specifies if the background of the button and the upImage and downImage are stored in sdram or not. If noSdram=CHECKED, then applying the disappear() IWC method could result in strange behavior and it could take a little longer for the images to be drawn on state changes, depending upon the size of the images. If the parameter is UNCHECKED, the Custom Button widget will allocate space in the SDRAM equivalent to the size of the button within the frame buffer times three. 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.01 - 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 Custom Button dimensions. Only one value is allowed; you cannot mix vertical alignments. Default is MIDDLE.