| A component that represents a radio button.
The RadioButton can be used as a single radio button
or one radio button among a group of radio button. A group
of radio button represents a multiple selection list which can have any
number of radio button selected, or none selected. A radio button can
represent a Boolean value, a String value,
or a developer defined Object value.
Detecting a selected radio button
The RadioButton uses both the selected
and selectedValue properties to pass information about
the radio button's selection status. The selected
property is used to indicate that the radio button is selected.
The selectedValue property is used to pass a data value,
a string by default, for the radio button. A radio button is considered to be
selected when the value of the selected property is equal
to the value of the selectedValue property. A radio button can
be initally selected by assigning the same value
to the selectedValue and the selected
properties. isChecked is called to determine
if this RadioButton is selected.
If the selectedValue property is not specified or its
value is null then the radio button behaves like a
boolean control. If the radio button is selected, the value of the
selected property is a true Boolean
instance. If the radio button 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 a radio button is part of a group, the selected radio
button is maintained as a request attribute in the
RequestMap. The name of the attribute is
the value of the radio button's name property.
The request attribute value is the
value of the selectedValue property of the
selected radio button.
The selected property
of the selected radio button within the group, will also contain the
value of the selectedValue property of the
respective selected radio button. If no radio buttons are selected,
no request attribute is created, however at least one radio button
must be selected.
Note that the RadioButton does not enforce the
requirement that at least one radio button must be selected.
The application should ensure that this requirement is met.
Using a radio button tag as a boolean control
If the selectedValue property is not specified or its
value is null then the radio button behaves like a
boolean control.
To use the RadioButton as a boolean control, do not
specify a value for the selectedValue property. The
radio button is selected if the selected property is not
null and has the value of a Boolean instance with a true
value. If the radio button is not selected, then the value of the
selected property is a false Boolean instance.
Note that using a boolean radio button in a group and
referencing the request property for the selected radio button is not
useful, since the value of the request property will be an
indistinguishable true value.
Using a RadioButton to represent a developer defined
value
The selectedValue property can be assigned a
developer defined object value to represent the value of a selected
radio button. If the radio button 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 radio button.
Using a RadioButton as one control in a group
The name property determines whether a
radio button is part of a group. A radio button is treated as part of a group
of radio buttons if the name property of the radio button is
assigned a value equal to the name property of the other
radio buttons in the group. In other words, all radio button of a
group have the same name property value. The group behaves
like a single selection list, where only one radio button
can be selected. The value of the name property must
be unique within the scope of the Form parent containing the
radio buttons.
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 radio button,
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 radio button, if the
label property is not null.
Add an image or label facet to the RadioButton if more
control over the properties of the subcomponents is needed.
Note that if a facet is exists, RadioButton properties
that would normally be assigned to the created subcomponent, will
not be assigned to the facet
Note that unexpected layout of the RadioButton 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
RadioButton.
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 RadioButton 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
RadioButton properties mentioned above, the value binding is
set on the subcomponent for that property.
| 