com.sun.rave.web.ui.component
Class Checkbox
java.lang.Object
javax.faces.component.UIComponent
javax.faces.component.UIComponentBase
javax.faces.component.UIOutput
javax.faces.component.UIInput
com.sun.rave.web.ui.component.SelectorBase
com.sun.rave.web.ui.component.Selector
com.sun.rave.web.ui.component.RbCbSelectorBase
com.sun.rave.web.ui.component.RbCbSelector
com.sun.rave.web.ui.component.CheckboxBase
com.sun.rave.web.ui.component.Checkbox
- All Implemented Interfaces:
- javax.faces.component.EditableValueHolder, SelectorManager, javax.faces.component.StateHolder, javax.faces.component.ValueHolder
- public class Checkbox
- extends CheckboxBase
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
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
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
ImageComponent for the image facet or
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 ImageComponent
component is created.
If the label property is not null and a label facet does not
exist then a Label component is
created.
The following Checkbox properties are assigned to the
subcomponents only if a facet does not exist.
For the 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 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.
| Fields inherited from class javax.faces.component.UIInput |
COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID |
|
Constructor Summary |
Checkbox()
Constructor for a Checkbox. |
|
Method Summary |
protected void |
addToRequestMap(javax.faces.context.FacesContext context,
java.lang.String groupName,
java.lang.Object selected)
|
static java.util.ArrayList |
getSelected(java.lang.String name)
Return an ArrayList containing the value of the
selectedValue property of each selected checkbox
in the group of checkboxes identified by the name
parameter. |
void |
validate(javax.faces.context.FacesContext context)
Update the request parameter that holds the value of the
selectedValue property of the selected check box. |
| Methods inherited from class com.sun.rave.web.ui.component.SelectorBase |
getItems, getLabel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getStyle, getStyleClass, getTabIndex, getToolTip, isDisabled, isReadOnly, isVisible, setDisabled, setItems, setLabel, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setStyle, setStyleClass, setTabIndex, setToolTip, setVisible |
| Methods inherited from class javax.faces.component.UIInput |
addValidator, addValueChangeListener, broadcast, decode, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValue, setValueChangeListener, updateModel, validateValue |
| Methods inherited from class javax.faces.component.UIOutput |
getConverter, getLocalValue, getValue, setConverter |
| Methods inherited from class javax.faces.component.UIComponentBase |
addFacesListener, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Methods inherited from interface javax.faces.component.ValueHolder |
getConverter, getLocalValue, getValue, setConverter |
Checkbox
public Checkbox()
- Constructor for a
Checkbox.
getSelected
public static java.util.ArrayList getSelected(java.lang.String name)
- Return an
ArrayList containing the value of the
selectedValue property of each selected checkbox
in the group of checkboxes identified by the name
parameter.
A Checkbox is one of a group of checkboxes
if more than on checkbox has the same value for the
name property.
When one of the checkboxes among that group is selected,
the value of its selectedValue property
is maintained within an ArrayList that is stored
in a request attribute identified by the value of its name
property.
- Parameters:
name - the value a Checkbox name property.
validate
public void validate(javax.faces.context.FacesContext context)
Update the request parameter that holds the value of the
selectedValue property of the selected check box.
If the name property has been set
a request attribute is created.
The value of the name property will
be used for the request attribute name and the value of the request
attribute will be an ArrayList containing the value of the
selectedValue property of the selected check boxes
that have the same name property value.
If no check box is selected then no request attribute
will be created.
The request attribute described above is available during
a ValueChangeEvent.
- Parameters:
context - The context of this request.
addToRequestMap
protected void addToRequestMap(javax.faces.context.FacesContext context,
java.lang.String groupName,
java.lang.Object selected)