com.sun.webui.jsf.component
Class ListSelector

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by javax.faces.component.UIInput
                  extended by com.sun.webui.jsf.component.WebuiInput
                      extended by com.sun.webui.jsf.component.Selector
                          extended by com.sun.webui.jsf.component.ListSelector
All Implemented Interfaces:
com.sun.webui.jsf.component.ComplexComponent, com.sun.webui.jsf.component.ListManager, com.sun.webui.jsf.component.SelectorManager, javax.faces.component.EditableValueHolder, javax.faces.component.NamingContainer, javax.faces.component.StateHolder, javax.faces.component.ValueHolder
Direct Known Subclasses:
AddRemove, DropDown, Listbox

public class ListSelector
extends Selector
implements com.sun.webui.jsf.component.ListManager, javax.faces.component.NamingContainer

Base component for UI components that allow the user to make a selection from a list of options using an HTML select element.


Field Summary
static java.lang.String LABEL_FACET
          The name of the label facet.
static java.lang.String LIST_ID
           
static java.lang.String VALUE_ID
           
static java.lang.String VALUE_LABEL_ID
           
 
Fields inherited from class javax.faces.component.UIInput
COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID
 
Fields inherited from interface javax.faces.component.NamingContainer
SEPARATOR_CHAR
 
Constructor Summary
ListSelector()
          Creates a new instance of ListSelector
 
Method Summary
 void checkSelectionModel(javax.faces.context.FacesContext context)
          Check that this component has a valuebinding that matches the value of the "multiple" attribute.
 java.lang.String getFamily()
          Return the family for this component.
 java.lang.String getFocusElementId(javax.faces.context.FacesContext context)
          Returns the id of an HTML element suitable to receive the focus.
 javax.faces.component.UIComponent getIndicatorComponent(javax.faces.context.FacesContext context, Label label)
          Return a component instance that can be referenced by a Label in order to evaluate the required and valid states of this component.
 javax.faces.component.UIComponent getLabelComponent()
          Return a component that implements the label for this ListSelector.
 java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
          Returns the absolute ID of an HTML element suitable for use as the value of an HTML LABEL element's for attribute.
 java.util.Iterator getListItems()
          Retrieve an Iterator of ListSelector.ListItem, to be used when evaluting the list items.
 java.util.Iterator getListItems(javax.faces.context.FacesContext context, boolean rulerAtEnd)
          Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.
 java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
          Deprecated.  
 javax.faces.component.UIComponent getReadOnlyValueComponent()
          Return a component that implements the read only value of this ListSelector.
 int getRows()
          The number of items to display, Integer.MIN_VALUE is returned if no value has been set, or there is no value binding.
 int getSeparatorLength()
          This method resets the options.
 java.lang.String getValueAsReadOnly(javax.faces.context.FacesContext context, java.lang.String separator)
          Return a string suitable for displaying the value in read only mode.
 java.lang.String[] getValueAsStringArray(javax.faces.context.FacesContext context)
          Get the value (the object representing the selection(s)) of this component as a String array.
 java.lang.String getWidth()
          Return a value suitable for the CSS width property to be applied to an HTML select element.
 boolean isLabelOnTop()
          If true, the label is rendered above the component.
 boolean isSeparators()
          Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list.
 boolean isVisible()
          Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.
 boolean mainListSubmits()
           
 void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
          Restore the state of this component.
 java.lang.Object saveState(javax.faces.context.FacesContext _context)
          Save the state of this component.
 void setLabelOnTop(boolean labelOnTop)
          If this attribute is true, the label is rendered above the component.
 void setRows(int rows)
          The number of items to display.
 void setSeparators(boolean separators)
          Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list.
 void setVisible(boolean visible)
          Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.
 void setWidth(java.lang.String width)
          width is a value for the CSS width property suitable for the select HTML element.
 
Methods inherited from class com.sun.webui.jsf.component.Selector
getConvertedValue, getItems, getLabel, getLabelLevel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getRendersChildren, getSelected, getStyle, getStyleClass, getTabIndex, getToolTip, getValueExpression, isDisabled, isMultiple, isReadOnly, setDisabled, setItems, setLabel, setLabelLevel, setMultiple, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setSelected, setStyle, setStyleClass, setTabIndex, setToolTip, setValueExpression, toString
 
Methods inherited from class com.sun.webui.jsf.component.WebuiInput
broadcast, getValidator, getValidatorExpression, getValueChangeListener, getValueChangeListenerExpression, processDecodes, processUpdates, processValidators, setConverter, setId, setImmediate, setRendered, setRequired, setValidatorExpression, setValueChangeListenerExpression
 
Methods inherited from class javax.faces.component.UIInput
addValidator, addValueChangeListener, decode, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidatorMessage, getValidators, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, removeValidator, removeValueChangeListener, resetValue, setConverterMessage, setLocalValueSet, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validate
 
Methods inherited from class javax.faces.component.UIOutput
getConverter, getLocalValue, getValue
 
Methods inherited from class javax.faces.component.UIComponentBase
encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRendererType, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, restoreAttachedState, saveAttachedState, setParent, setRendererType, setTransient, setValueBinding
 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getContainerClientId
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.sun.webui.jsf.component.ListManager
getToolTip
 
Methods inherited from interface javax.faces.component.EditableValueHolder
addValidator, addValueChangeListener, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValueChangeListener
 
Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue, getValue, setConverter, setValue
 
Methods inherited from interface com.sun.webui.jsf.component.SelectorManager
getClientId, getOnChange, getStyle, getStyleClass, getTabIndex, isDisabled, isMultiple, isReadOnly
 

Field Detail

LABEL_FACET

public static final java.lang.String LABEL_FACET
The name of the label facet.

See Also:
Constant Field Values

VALUE_ID

public static final java.lang.String VALUE_ID
See Also:
Constant Field Values

VALUE_LABEL_ID

public static final java.lang.String VALUE_LABEL_ID
See Also:
Constant Field Values

LIST_ID

public static final java.lang.String LIST_ID
See Also:
Constant Field Values
Constructor Detail

ListSelector

public ListSelector()
Creates a new instance of ListSelector

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:
getFamily in class Selector

checkSelectionModel

public void checkSelectionModel(javax.faces.context.FacesContext context)
Check that this component has a valuebinding that matches the value of the "multiple" attribute.

Parameters:
context - The FacesContext of the request

getListItems

public java.util.Iterator getListItems(javax.faces.context.FacesContext context,
                                       boolean rulerAtEnd)
                                throws javax.faces.FacesException
Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.

Specified by:
getListItems in interface com.sun.webui.jsf.component.ListManager
Returns:
an Iterator over ListItem.
Throws:
javax.faces.FacesException

getListItems

public java.util.Iterator getListItems()
                                throws javax.faces.FacesException
Retrieve an Iterator of ListSelector.ListItem, to be used when evaluting the list items. If the list items are needed by the renderer, use getListItems(context, rulerAtEnd) instead.

Returns:
an Iterator over ListItem.
Throws:
javax.faces.FacesException

getSeparatorLength

public int getSeparatorLength()
This method resets the options. Use this only if you need to add or remove options after the component has been rendered once. public void resetOptions() { listItems = null; }


getLabelComponent

public javax.faces.component.UIComponent getLabelComponent()
Return a component that implements the label for this ListSelector. If a facet named label is found that component is returned. Otherwise a Label component is returned. It is assigned the id
getId() + "_label"

If the facet is not defined then the returned Label component is re-intialized every time this method is called.

Returns:
a label component for this ListSelector

getReadOnlyValueComponent

public javax.faces.component.UIComponent getReadOnlyValueComponent()
Return a component that implements the read only value of this ListSelector. If a facet named readOnly is found that component is returned. Otherwise a StaticText component is returned. It is assigned the id
getId() + "_readOnly"

If the facet is not defined then the returned StaticText component is re-intialized every time this method is called.

Specified by:
getReadOnlyValueComponent in interface com.sun.webui.jsf.component.ListManager
Returns:
a component that represents the read only value of this ListSelector

getValueAsStringArray

public java.lang.String[] getValueAsStringArray(javax.faces.context.FacesContext context)
Get the value (the object representing the selection(s)) of this component as a String array.

Specified by:
getValueAsStringArray in interface com.sun.webui.jsf.component.ListManager
Parameters:
context - The FacesContext of the request

getLabeledElementId

public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
Returns the absolute ID of an HTML element suitable for use as the value of an HTML LABEL element's for attribute. If the ComplexComponent has sub-compoents, and one of the sub-components is the target of a label, if that sub-component is a ComplexComponent, then getLabeledElementId must called on the sub-component and the value returned. The value returned by this method call may or may not resolve to a component instance.

If isReadOnly returns true, then the getReadOnlyValueComponent method is called. If the component instance returned is a ComplexComponent then getLabeledElementId is called on it and the value returned, else its client id is returned.

Specified by:
getLabeledElementId in interface com.sun.webui.jsf.component.ComplexComponent
Parameters:
context - The FacesContext used for the request
Returns:
An abolute id suitable for the value of an HTML LABEL element's for attribute.

getFocusElementId

public java.lang.String getFocusElementId(javax.faces.context.FacesContext context)
Returns the id of an HTML element suitable to receive the focus. If the ComplexComponent has sub-compoents, and one of the sub-components is to reveive the focus, if that sub-component is a ComplexComponent, then getFocusElementId must called on the sub-component and the value returned. The value returned by this method call may or may not resolve to a component instance.

This implementations returns the value of getLabeledElementId.

Specified by:
getFocusElementId in interface com.sun.webui.jsf.component.ComplexComponent
Parameters:
context - The FacesContext used for the request

getIndicatorComponent

public javax.faces.component.UIComponent getIndicatorComponent(javax.faces.context.FacesContext context,
                                                               Label label)
Return a component instance that can be referenced by a Label in order to evaluate the required and valid states of this component.

Specified by:
getIndicatorComponent in interface com.sun.webui.jsf.component.ComplexComponent
Parameters:
context - The current FacesContext instance
label - The Label that labels this component.
Returns:
a UIComponent in order to evaluate the required and valid states.

getPrimaryElementID

public java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
Deprecated. 

Implement this method so that it returns the DOM ID of the HTML element which should receive focus when the component receives focus, and to which a component label should apply. Usually, this is the first element that accepts input.

Specified by:
getPrimaryElementID in interface com.sun.webui.jsf.component.ComplexComponent
Parameters:
context - The FacesContext for the request
Returns:
The client id, also the JavaScript element id
See Also:
getLabeledElementId(javax.faces.context.FacesContext), getFocusElementId(javax.faces.context.FacesContext)

getValueAsReadOnly

public java.lang.String getValueAsReadOnly(javax.faces.context.FacesContext context,
                                           java.lang.String separator)
Return a string suitable for displaying the value in read only mode. The default is to separate the list values with a comma.

Parameters:
context - The FacesContext
Throws:
javax.faces.FacesException - If the list items cannot be processed

mainListSubmits

public boolean mainListSubmits()
Specified by:
mainListSubmits in interface com.sun.webui.jsf.component.ListManager

isLabelOnTop

public boolean isLabelOnTop()

If true, the label is rendered above the component. If false, the label is rendered next to the component. The default is false.


setLabelOnTop

public void setLabelOnTop(boolean labelOnTop)

If this attribute is true, the label is rendered above the component. If it is false, the label is rendered next to the component. The default is false.

See Also:
isLabelOnTop()

getRows

public int getRows()
The number of items to display, Integer.MIN_VALUE is returned if no value has been set, or there is no value binding. Subclasses should provide a reasonable default.

Specified by:
getRows in interface com.sun.webui.jsf.component.ListManager
Returns:
The number items to display.

setRows

public void setRows(int rows)
The number of items to display.

See Also:
getRows()

isSeparators

public boolean isSeparators()

Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list. The default value is true. If false, no separators are shown. To manually specify the location of separators, set this flag to false and place instances of com.sun.webui.jsf.model.Separator between the relevant com.sun.webui.jsf.model.Option instances when specifying the items attribute.


setSeparators

public void setSeparators(boolean separators)

Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list. The default value is true. If false, no separators are shown. To manually specify the location of separators, set this flag to false and place instances of com.sun.webui.jsf.model.Separator between the relevant com.sun.webui.jsf.model.Option instances when specifying the items attribute.

See Also:
isSeparators()

isVisible

public boolean isVisible()

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

Specified by:
isVisible in interface com.sun.webui.jsf.component.ListManager
Overrides:
isVisible in class Selector

setVisible

public void setVisible(boolean visible)

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

Overrides:
setVisible in class Selector
See Also:
isVisible()

getWidth

public java.lang.String getWidth()
Return a value suitable for the CSS width property to be applied to an HTML select element.

This ListSelector base class interprets a null value to imply that the select element should size itself based on the length of the longest option.

Specified by:
getWidth in interface com.sun.webui.jsf.component.ListManager
Returns:
The value used to determine the width of a select HTML element.

setWidth

public void setWidth(java.lang.String width)
width is a value for the CSS width property suitable for the select HTML element. As a CSS string property value, width is assumed to contain the units. For example:

The value is not parsed by ListSelector and may not be by its subclasses. It is intended to be applied directly to the style attribute of the select element. If width is null, ListSelector behavior will assume the size of the select element will be based on the length of the longest Option item's text property, and if that is not set, its label property.

Parameters:
width - The width of the listbox.
See Also:
getWidth(), The Option.label property

restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:
restoreState in interface javax.faces.component.StateHolder
Overrides:
restoreState in class Selector

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:
saveState in interface javax.faces.component.StateHolder
Overrides:
saveState in class Selector


Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.