| A component that represents a checkbox.
The Checkbox can be used as a single checkbox
or one checkbox among a group of checkboxes. A group
of checkboxes represents a multiple selection list which can have any
number of checkboxes selected, or none selected. A checkbox can
represent a Boolean value, a String value,
or a developer defined Object value.
Detecting a selected checkbox
The Checkbox uses both the selected
and selectedValue properties to pass information about
the checkbox's selection status. The selected
property is used to indicate that the checkbox is selected.
The selectedValue property is used to pass a data value,
a string by default, for the checkbox. A checkbox is considered to be
selected when the value of the selected property is equal
to the value of the selectedValue property. A checkbox can
be initally selected by assigning the same value
to the selectedValue and the selected
properties. isChecked is called to determine
if this Checkbox is selected.
If the selectedValue property is not specified or its
value is null then the checkbox behaves like a
boolean control. If the checkbox is selected, the value of the
selected property is a true Boolean
instance. If the checkbox is not selected, the value of the
selected property will be a false Boolean
instance.
Note that a value binding expression that evaluates to a
primitive boolean value can be assigned to the selected
property. Proper type coercion from Boolean to
boolean occurs.
When checkboxes are part of a group, an ArrayList of
selected checkboxes is maintained. If any checkboxes within a group are
selected, a request attribute whose name is the value of the
name property is created and added to the
RequestMap. The request attribute value is an
ArrayList containing the value of the
selectedValue property of each selected
checkbox. If no checkboxes are selected, no request attribute is
created. The selected property of each selected checkbox
within the group will also contain the value of the
selectedValue property of the respective selected checkbox.
Using a checkbox tag as a boolean control
If the selectedValue property is not specified or its
value is null then the checkbox behaves like a
boolean control.
To use the Checkbox as a boolean control, do not
specify a value for the selectedValue property. The
checkbox is selected if the selected property is not
null and has the value of a Boolean instance with a true
value. If the checkbox is not selected, then the value of the
selected property is a false Boolean instance.
Note that using a boolean checkbox in a group and
referencing the request property for the selected checkboxes is not
useful, since the value of the request property will be an ArrayList
of indistinguishable true values.
Using a Checkbox to represent a developer defined
value
The selectedValue property can be assigned a
developer defined object value to represent the value of a selected
checkbox. If the checkbox is selected, the value of the selected
property is assigned the value of the selectedValue
property.
If the value of the selectedValue property is a
developer defined object, a Converter must be registered
to convert to and from a String value.
In addition the object must support an
equals method that returns true when the
value of the selectedValue property is compared to
the selected property value in order to detect a
selected checkbox.
Using a Checkbox as one control in a group
The name property determines whether a
checkbox is part of a group. A checkbox is treated as part of a group
of checkboxes if the name property of the checkbox is
assigned a value equal to the name property of the other
checkboxes in the group. In other words, all checkboxes of a group have the
same name property value. The group behaves
like a multiple selection list, where zero or more checkboxes
can be selected. The value of the name property must
be unique within the scope of the Form parent containing the
checkboxes.
Facets
The following facets are supported:
- image If the image facet exists, it replaces the
com.sun.rave.web.ui.component.ImageComponent subcompoent
normally created for the image associated with the checkbox
if the
imageURL property is not null.
- label If the label facet exists, it replaces the
com.sun.rave.web.ui.component.Label subcomponent normally
created for the label associated with the checkbox, if the
label property is not null.
Add an image or label facet to the Checkbox if more
control over the properties of the subcomponents is needed.
Note that if a facet is exists, Checkbox properties
that would normally be assigned to the created subcomponent, will
not be assigned to the facet
Note that unexpected layout of the Checkbox may occur
if the component specified by the facet is not a
com.sun.rave.web.ui.component.ImageComponent for the image facet or
com.sun.rave.web.ui.component.Label for the label facet.
ImageComponent and Label subcomponents
An image and a label may be associated with the Checkbox.
If the imageURL property is not null and an image facet
does not exist then a
com.sun.rave.web.ui.component.ImageComponent component is created.
If the label property is not null and a label facet does not
exist then a
com.sun.rave.web.ui.component.Label component is
created.
The following Checkbox properties are assigned to the
subcomponents only if a facet does not exist.
For the
com.sun.rave.web.ui.component.ImageComponent subcomponent
- this.getId() + "_image" is assigned to the
id property.
- this.getImageURL() is assigned to the
url property.
- this.getToolTip() is assigned to the
toolTip property.
- this.getToolTip() is assigned to the
alt property.
- this.isVisible() is assigned to the
visible property.
- this.isRendered() is assigned to the
renderer property.
For the
com.sun.rave.web.ui.component.Label subcomponent
- this.getId() + "_label" is assigned to the
id
property.
- this.getClientId() is assigned to the
for
property.
- this.getLabel() is assigned to the
text property.
- this.getLabelLevel is assigned to the
labelLevel property.
- this.getToolTip is assigned to the
toolTip property.
- this.isVisible is assigned to the
visible property.
- this.isRendered is assigned to the
renderer property.
Note that if a value binding exists for one of the Checkbox
properties mentioned above, the value binding is set on the subcomponent
for that property.
| 