Checkbox Widget (CheckBox.class)

A checkbox is a labeled, square box used to invoke a function (or set of functions) whose argument is the value of the checkbox. To toggle (check or uncheck) a checkbox, click on the checkbox (or label). Checkboxes can also be grouped to invoke functions whose argument is the cumulative value of all checked boxes (logical ORing). Boxes that have the same groupName are considered part of a checkbox group. Within a checkbox group, any combination of boxes can be checked. If none of the boxes are set within a group, then 0x00 is the href function call argument. Therefore, you must give each box a checked value that is different on a binary bit level. If one box has a checked value of 0x01, then another box could have a value of 0x02, and the next a value of 0x04 (not 0x03 because that would be the ORed value of boxes 1 and 2 when checked).

Checkbox Parameter Attributes:

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

Parameter="boxAlign" value="LEFT" or "RIGHT" — Specifies the location of the checkbox in relation to the label text.

Parameter="checkedValue" value="number" — Specifies the checked box value. If the box is part of a group, single bits should be used, such as 0x01, 0x02, 0x04 etc. All boxes within a checkbox group must be assigned unique binary numbers. That is, if one checkbox has a value of 0x01(bit 0), no other checkbox within the group can use bit 0. If the box is part of a group, the range is 1 - 255 (0x01 - 0xFF). If a lone box, the checkedValue can be a BYTE, WORD or STRING. See note regarding Control Widget intrinsic values.

Parameter="font" value="font, font size" — Specifies the font and font size used for the checkbox label. See Amulet GEM Font Converter for more information regarding the creation of .auf font files. Default font 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="BOLD" or "ITALIC" or "PLAIN" — Specifies the style associated with the checkbox 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="groupName" value="text" — For a grouped checkbox, specifies the checkbox group assignment. Attribute not needed if a lone checkbox.

Parameter="href" value="function(s)" — The function (or multiple/sequenced functions) invoked when a checkbox is toggled (checked or unchecked). If the checkbox is NOT part of a checkbox group, the argument of the function is determined by the state of the checkbox. If checked, the argument is determined by the checkedValue parameter; if unchecked, the argument is determined by the unCheckedvalue parameter. If the checkbox is part of a group, the argument is the cumulative value of all "checked" boxes (logical ORing). All checkboxes within a group must call the same href function(s). See Appendix B for all available href functions for the checkbox widget.

Parameter="initialCondition" value="ON" or "OFF" or "FromInitHref" — Specifies the initial condition of a checkbox when the page is loaded; ON specifies a checked box; OFF an unchecked box. If FromInitHref is selected, the function specified by the initHref attribute is called. The returned value determines the initial condition of all checkboxes within the group. If part of a group, a box is checked when its checkedValue corresponds to a set bit in the returned byte (logical ANDing). If a lone checkbox, the box is checked when its internalNumber equals the returned initHref value.

Parameter="label" value="text" — Specifies the name that appears to the right or left of the checkbox.

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 Checkbox Parameter Attributes:

Parameter="noSdram" value="CHECKED" or "UNCHECKED" — Specifies if the background of the Check Box and the three images are to be 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 Check Box times four within the frame buffer. UNCHECKED is the default.

Parameter="unCheckedvalue" value="number" — Specifies the unchecked box value. This attribute is only valid when NOT part of a checkbox group. The checkedValue can be a BYTE, WORD or STRING. See note regarding Control Widget intrinsic values.

Parameter="emptyImage" value="image" — Specifies the image to use when the checkbox is in the unchecked state. If this attribute is not present, then a default image, an empty black and white square, is used. (Images can be either .GIF, .JPG or .PNG.)

Parameter="fullImage" value="image" — Specifies the image to use when the checkbox is in the checked state. If this attribute is not present, then a default image, a grayed out block and white square, is used. (Images can be either .GIF, .JPG or .PNG.)

Parameter="hrefOnHitOnly" value="CHECKED" or "UNCHECKED" — Specifies if the check box href function(s) is launched only upon a "hit" or not. By default, hrefOnHitOnly is UNCHECKED, which means if the check box has an initHref function, the href of the check box (group or lone) is launched upon loading the page. The href is also launched after a forceUpdate() call. By setting hrefOnHitOnly to CHECKED, the href will only be launched upon the check box physically being selected or upon a forceHit() call.

Parameter="initHref" value="function" — Specifies the function called when the page is loaded. Use this attribute when FromInitHref is used as the initialCondition. All boxes within a group must have the same function(s). If part of a group, the function must return a BYTE value, and the value returned is compared to the checkedValue. If the checkedValue bit is set in the returned value, the box will initially start out in the "on" position. If a lone check box, then the returned value is compared to the internalNumber and if equal, the lone check box initially starts out in the "on" position. See Appendix B for all available functions.

Parameter="internalNumber" value="number" — Specifies the internal number of the lone checkbox, which is used to determine if the initial condition of the lone check box is on or off, if FromInitHref is used as the initialCondition. Should only be used if using initHref. If the value returned from the initHref function matches the internalNumber of the lone check box, then the check box starts out in the "on" position. If the internalNumber is not specified, the checkedValue is used instead.

Parameter="trackingImage" value="image" — Specifies the image to use when the checkbox is in the pen down state. If this attribute is not present, then a default image, a black and white square with a check in it, is used. (Images can be either .GIF, .JPG, or .PNG.)