com.arsdigita.bebop
Class List

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.List
All Implemented Interfaces:
BebopConstants, Cloneable, Component, Lockable
Direct Known Subclasses:
PageErrorDisplay, SimpleQuestionnaireList, UserList

public class List
extends SimpleComponent
implements BebopConstants

A List, similar to a javax.swing.JList, that keeps track of a sequence of items and selections of one or more of these items. A separate model, ListModel, is used to represent the items in the list.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/List.java#9 $
Author:
David Lutterkort
See Also:
ListModel, ListModelBuilder, ListCellRenderer

Field Summary
static ListModel EMPTY_MODEL
          A ListModel that has no rows.
static int HORIZONTAL
          Horizontal List layout.
static String SELECT_EVENT
          The name of the event the list sets when producing links that change which item is selected.
static String SELECTED
          The name of the StringParameter that the list uses to keep track of which item is selected.
static String versionId
           
static int VERTICAL
          Vertical List layout.
 
Fields inherited from class com.arsdigita.bebop.SimpleComponent
m_attr
 
Fields inherited from interface com.arsdigita.bebop.util.BebopConstants
BEBOP_BORDER, BEBOP_BOXPANEL, BEBOP_CELL, BEBOP_CHECKBOX, BEBOP_CHECKBOXGROUP, BEBOP_COLUMNPANEL, BEBOP_DATE, BEBOP_DATETIME, BEBOP_DHTMLEDITOR, BEBOP_FORMERRORS, BEBOP_FORMWIDGET, BEBOP_GRIDPANEL, BEBOP_LIST, BEBOP_MULTISELECT, BEBOP_OPTION, BEBOP_PAD, BEBOP_PADFRAME, BEBOP_PANELROW, BEBOP_PORTAL, BEBOP_PORTLET, BEBOP_RADIO, BEBOP_RADIOGROUP, BEBOP_SEG_BODY, BEBOP_SEG_HEADER, BEBOP_SEG_PANEL, BEBOP_SEGMENT, BEBOP_SELECT, BEBOP_TABLE, BEBOP_TABLEBODY, BEBOP_TABLEROW, BEBOP_TEXTAREA
 
Fields inherited from interface com.arsdigita.bebop.Component
BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE
 
Constructor Summary
List()
          Creates an empty List.
List(ListModelBuilder b)
          Creates a new List that uses the specified list model builder to generate per-request ListModels.
List(Map map)
          Creates a new List from a map.
List(Object[] values)
          Creates a new List from an array of objects.
List(SingleSelectionModel selection)
          Create an empty List.
 
Method Summary
 void addActionListener(ActionListener l)
          Adds an action listener.
 void addChangeListener(ChangeListener l)
          Adds a change listener.
 void clearSelection(PageState state)
          Clears the selection in the request represented by state.
protected  ChangeListener createChangeListener()
          Creates the change listener that is used for forwarding change events fired by the selection model to change listeners registered with the list.
protected  void fireActionEvent(PageState state)
          Fires an action event signalling that the list received the request submission.
protected  void fireStateChanged(PageState state)
          Fires a change event to signal that the selected list item has changed in the request represented by state.
 void generateXML(PageState state, Element parent)
          Generates XML representing the items in the list.
 ListCellRenderer getCellRenderer()
          Returns the renderer currently used for rendering list items.
 Component getEmptyView()
          Gets the empty view component.
 int getLayout()
          Retrieve the current List layout.
 ListModel getModel(PageState state)
          Gets the list model used in processing the request represented by state.
 ListModelBuilder getModelBuilder()
          Returns the model builder currently used to build each request-specific ListModel.
 Object getSelectedKey(PageState state)
          Gets the key for the selected list item.
 SingleSelectionModel getSelectionModel()
          Gets the selection model.
 boolean getStateParamsAreRegistered()
           
 boolean isSelected(PageState state)
          Returns true if one of the list items is currently selected.
 void register(Page p)
          Registers this List and its state parameter(s) with the specified page.
 void removeActionListener(ActionListener l)
          Removes a previously added action listener.
 void removeChangeListener(ChangeListener l)
          Removes a change listener.
 void respond(PageState state)
          Responds to a request in which this List was the targetted component.
 void setCellRenderer(ListCellRenderer r)
          Sets the cell renderer to be used when generating output with or generateXML.
 void setEmptyView(Component c)
          Sets the empty view component, which is shown if there are no items in the list.
 void setLayout(int layout)
          Set the current List layout.
 void setListData(Map map)
          Sets the list to use the entries in map.
 void setListData(Object[] values)
          Sets the list to use for the values in values.
 void setModelBuilder(ListModelBuilder b)
          Sets the model builder used to build each request-specific ListModel.
 void setSelectedKey(PageState state, String key)
          Sets the selection to the one with the specified key.
 void setSelectionModel(SingleSelectionModel m)
          Sets the selection model that the list uses to keep track of the currently selected list item.
 void setStateParamsAreRegistered(boolean val)
          This method is part of a mechanism to freakishly allow List's to be used as parent classes for components that do not have their state params registered with the page.
 
Methods inherited from class com.arsdigita.bebop.SimpleComponent
children, clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, lock, register, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible
 
Methods inherited from class com.arsdigita.bebop.Completable
addCompletionListener, fireCompletionEvent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

SELECTED

public static final String SELECTED
The name of the StringParameter that the list uses to keep track of which item is selected.

See Also:
Constant Field Values

SELECT_EVENT

public static final String SELECT_EVENT
The name of the event the list sets when producing links that change which item is selected.

See Also:
Constant Field Values

VERTICAL

public static final int VERTICAL

Vertical List layout.

See Also:
Constant Field Values

HORIZONTAL

public static final int HORIZONTAL

Horizontal List layout.

See Also:
Constant Field Values

EMPTY_MODEL

public static final ListModel EMPTY_MODEL
A ListModel that has no rows.

Constructor Detail

List

public List(ListModelBuilder b)
Creates a new List that uses the specified list model builder to generate per-request ListModels.

Parameters:
b - the model builder used for this list

List

public List()
Creates an empty List.


List

public List(SingleSelectionModel selection)
Create an empty List.


List

public List(Object[] values)
Creates a new List from an array of objects. Uses an internal ListModelBuilder. Each ListModel that is built will iterate through the entries of the object, returning the objects from calls to ListModel.getElement() and the corresponding index, which is converted to a String from calls to ListModel.getKey().

Parameters:
values - an array of items
See Also:
setListData(Object[] v)

List

public List(Map map)
Creates a new List from a map. Uses an internal ListModelBuilder. Each ListModel that is built will iterate through the entries in map in the order in which they are returned by map.entrySet().iterator(). Calls to ListModel.getElement() return one value in map. Calls to ListModel.getElement() return the corresponding key, which is converted to a String by calling toString() on the key.

Parameters:
map - a key-value mapping for the list items
Method Detail

register

public void register(Page p)
Registers this List and its state parameter(s) with the specified page.

Specified by:
register in interface Component
Overrides:
register in class SimpleComponent
Parameters:
p - the page this list is contained in

respond

public void respond(PageState state)
             throws javax.servlet.ServletException
Responds to a request in which this List was the targetted component. Calls to this method should only be made through links generated by this list.

Determines the new selected element and fires a ChangeEvent if it has changed. After that, fires an ActionEvent.

Specified by:
respond in interface Component
Overrides:
respond in class SimpleComponent
Parameters:
state - the state of the current request
Throws:
javax.servlet.ServletException - if the control event is unknown.
See Also:
fireStateChanged, fireActionEvent

generateXML

public void generateXML(PageState state,
                        Element parent)
Generates XML representing the items in the list. The items are formatted using a ListCellRenderer. generateXML is called on each component returned by the renderer.

The XML that is generated has the following form:

   <bebop:list mode="single" %bebopAttr;>
     <bebop:cell [selected="selected"] key="itemKey">
        ... XML generated for component returned by renderer ...
     </bebop:cell>
     ... more <bebop:cell> elements, one for each list item ...
   </bebop:list>

Specified by:
generateXML in interface Component
Overrides:
generateXML in class SimpleComponent
Parameters:
state - the state of the current request
parent - the element into which XML is generated
See Also:
ListCellRenderer

getLayout

public int getLayout()

Retrieve the current List layout.

Returns:
List.VERTICAL or List.HORIZONTAL

setLayout

public void setLayout(int layout)

Set the current List layout.

Parameters:
layout - New layout value, must be List.VERTICAL or List.HORIZONTAL

setStateParamsAreRegistered

public void setStateParamsAreRegistered(boolean val)
This method is part of a mechanism to freakishly allow List's to be used as parent classes for components that do not have their state params registered with the page. An example of a situation like this is Form ErrorDisplay being used in a Metaform


getStateParamsAreRegistered

public boolean getStateParamsAreRegistered()

getCellRenderer

public final ListCellRenderer getCellRenderer()
Returns the renderer currently used for rendering list items.

Returns:
the current list cell renderer.
See Also:
setCellRenderer, ListCellRenderer

setCellRenderer

public final void setCellRenderer(ListCellRenderer r)
Sets the cell renderer to be used when generating output with or generateXML.

Parameters:
r - a ListCellRenderer value
See Also:
ListCellRenderer

getModelBuilder

public final ListModelBuilder getModelBuilder()
Returns the model builder currently used to build each request-specific ListModel.

Returns:
a ListModelBuilder value.
See Also:
setModelBuilder, ListModelBuilder

setModelBuilder

public final void setModelBuilder(ListModelBuilder b)
Sets the model builder used to build each request-specific ListModel.

Parameters:
b - a ListModelBuilder value
See Also:
ListModelBuilder

setEmptyView

public final void setEmptyView(Component c)
Sets the empty view component, which is shown if there are no items in the list. This component must be stateless. For example, it could be an Image or a Label.

Parameters:
c - the new empty view component

getEmptyView

public final Component getEmptyView()
Gets the empty view component. The empty view component is shown if there are no items in the list.

Returns:
the empty view component.

getModel

public ListModel getModel(PageState state)
Gets the list model used in processing the request represented by state.

Parameters:
state - the state of the current request
Returns:
the list model used in processing the request represented by state.

setListData

public void setListData(Object[] values)
Sets the list to use for the values in values. Each ListModel that is built will iterate through the entries of the object, returning the objects from calls to ListModel.getElement() and the corresponding index, which is converted to a String from calls to ListModel.getKey().

Parameters:
values - an array of items

setListData

public void setListData(Map map)
Sets the list to use the entries in map. Each ListModel that is built will iterate through the entries in map in the order in which they are returned by map.entrySet().iterator(). Calls to ListModel.getElement() return one value in map. Calls to ListModel.getElement() return the corresponding key, which is converted to a String by calling toString() on the key.

Parameters:
map - a key-value mapping for the list items

getSelectionModel

public final SingleSelectionModel getSelectionModel()
Gets the selection model. The model keeps track of which list item is currently selected, and can be used to manipulate the selection programmatically.

Returns:
the model used by the list to keep track of the selected list item.

setSelectionModel

public final void setSelectionModel(SingleSelectionModel m)
Sets the selection model that the list uses to keep track of the currently selected list item.

Parameters:
m - the new selection model

getSelectedKey

public Object getSelectedKey(PageState state)
Gets the key for the selected list item. This will only be a valid key if isSelected is true.

Parameters:
state - the state of the current request
Returns:
the key for the selected list item.

setSelectedKey

public void setSelectedKey(PageState state,
                           String key)
Sets the selection to the one with the specified key. If key was not already selected, fires the ChangeEvent.

Parameters:
state - the state of the current request
key - the key for the selected list item
See Also:
fireStateChanged

isSelected

public boolean isSelected(PageState state)
Returns true if one of the list items is currently selected.

Parameters:
state - the state of the current request
Returns:
true if one of the list items is selected false otherwise.

clearSelection

public void clearSelection(PageState state)
Clears the selection in the request represented by state.

Parameters:
state - the state of the current request

createChangeListener

protected ChangeListener createChangeListener()
Creates the change listener that is used for forwarding change events fired by the selection model to change listeners registered with the list. The returned change listener refires the event with the list, rather than the selection model, as source.

Returns:
the change listener used internally by the list.

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a change listener. A change event is fired whenever the selected list item changes during the processing of a request. The change event that listeners receive names the list as the source.

Parameters:
l - the change listener to run when the selected item changes in a request

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a change listener. The listener should have been previously added with addChangeListener, although no error is signalled if the change listener is not found among the list's listeners.

Parameters:
l - the change listener to remove from the list

fireStateChanged

protected void fireStateChanged(PageState state)
Fires a change event to signal that the selected list item has changed in the request represented by state. The source of the event is the list.

Parameters:
state - the state of the current request

addActionListener

public void addActionListener(ActionListener l)
Adds an action listener. This method is run whenever respond is called on the list. This gives clients a way to track mouse clicks received by the list.

See Also:
respond

removeActionListener

public void removeActionListener(ActionListener l)
Removes a previously added action listener.

See Also:
addActionListener

fireActionEvent

protected void fireActionEvent(PageState state)
Fires an action event signalling that the list received the request submission. All registered action listeners are run. The source of the event is the list.

Parameters:
state - the state of the current request
See Also:
respond


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC