org.apache.pivot.wtk
Class ListView

java.lang.Object
  extended by org.apache.pivot.wtk.Component
      extended by org.apache.pivot.wtk.ListView
All Implemented Interfaces:
ConstrainedVisual, Visual

@DefaultProperty(value="listData")
public class ListView
extends Component

Component that displays a sequence of items, optionally allowing a user to select or check one or more items.


Nested Class Summary
static interface ListView.ItemBindMapping
          Translates between item position and bind context data during data binding.
static interface ListView.ItemEditor
          List view item editor interface.
static interface ListView.ItemRenderer
          Renderer interface to customize the appearance of items in a ListView.
static interface ListView.ListDataBindMapping
          Translates between list and bind context data during data binding.
static class ListView.SelectMode
          Enumeration defining supported selection modes.
static interface ListView.Skin
          List view skin interface.
 
Nested classes/interfaces inherited from class org.apache.pivot.wtk.Component
Component.DecoratorSequence, Component.StyleDictionary, Component.UserDataDictionary
 
Constructor Summary
ListView()
          Creates a list view populated with an empty array list.
ListView(List<?> listData)
          Creates a list view populated with the given list data.
 
Method Summary
 boolean addSelectedIndex(int index)
          Adds a single index to the selection.
 Sequence<Span> addSelectedRange(int start, int end)
          Adds a range of indexes to the selection.
 Sequence<Span> addSelectedRange(Span range)
          Adds a range of indexes to the selection.
 void clear()
          Clears any bound values in the component.
 void clearCheckmarks()
          Clears the checked state of all checked items.
 void clearSelection()
          Clears the selection.
 ImmutableList<Integer> getCheckedIndexes()
          Returns the indexes of currently checked items.
 ListView.ItemBindMapping getCheckedItemsBindMapping()
           
 BindType getCheckedItemsBindType()
           
 String getCheckedItemsKey()
           
 boolean getCheckmarksEnabled()
          Returns the current check mode.
 Filter<?> getDisabledCheckmarkFilter()
          Returns the disabled checkmark filter, which determines which checkboxes are interactive and which are not.
 Filter<?> getDisabledItemFilter()
          Returns the disabled item filter.
 int getFirstSelectedIndex()
          Returns the first selected index.
 int getItemAt(int y)
          Returns the index of the item at a given location.
 Bounds getItemBounds(int index)
          Returns the bounding area of a given item.
 ListView.ItemEditor getItemEditor()
          Returns the editor used to edit items in this list.
 int getItemIndent()
          Returns the item indent.
 ListView.ItemRenderer getItemRenderer()
          Returns the item renderer used for items in this list.
 int getLastSelectedIndex()
          Returns the last selected index.
 List<?> getListData()
          Returns the list data.
 ListView.ListDataBindMapping getListDataBindMapping()
           
 BindType getListDataBindType()
           
 String getListDataKey()
          Returns name of the key that is used in context binding.
 ListenerList<ListViewBindingListener> getListViewBindingListeners()
           
 ListenerList<ListViewItemListener> getListViewItemListeners()
          Returns the list view item listener list.
 ListenerList<ListViewItemStateListener> getListViewItemStateListeners()
          Returns the list view item state listener list.
 ListenerList<ListViewListener> getListViewListeners()
          Returns the list view listener list.
 ListenerList<ListViewSelectionListener> getListViewSelectionListeners()
          Returns the list view selection detail listener list.
 int getSelectedIndex()
          Returns the currently selected index, even when in multi-select mode.
 Object getSelectedItem()
           
 ListView.ItemBindMapping getSelectedItemBindMapping()
           
 BindType getSelectedItemBindType()
           
 String getSelectedItemKey()
           
 Sequence<?> getSelectedItems()
           
 ListView.ItemBindMapping getSelectedItemsBindMapping()
           
 BindType getSelectedItemsBindType()
           
 String getSelectedItemsKey()
           
 ImmutableList<Span> getSelectedRanges()
          Returns the currently selected ranges.
 ListView.SelectMode getSelectMode()
          Returns the current selection mode.
 boolean isCheckmarkDisabled(int index)
          Tells whether or not an item's checkmark is disabled.
 boolean isItemChecked(int index)
          Returns an item's checked state.
 boolean isItemDisabled(int index)
          Returns an item's disabled state.
 boolean isItemSelected(int index)
          Returns the selection state of a given index.
 void load(Object context)
          Copies bound values from the bind context to the component.
 boolean removeSelectedIndex(int index)
          Removes a single index from the selection.
 Sequence<Span> removeSelectedRange(int start, int end)
          Removes a range of indexes from the selection.
 Sequence<Span> removeSelectedRange(Span range)
          Removes a range of indexes from the selection.
 void selectAll()
          Selects all items in the list.
 void setCheckedItemsBindMapping(ListView.ItemBindMapping checkedItemsBindMapping)
           
 void setCheckedItemsBindType(BindType checkedItemsBindType)
           
 void setCheckedItemsKey(String checkedItemsKey)
           
 void setCheckmarksEnabled(boolean checkmarksEnabled)
          Enables or disables checkmarks.
 void setDisabledCheckmarkFilter(Filter<?> disabledCheckmarkFilter)
          Sets the disabled checkmark filter, which determines which checkboxes are interactive and which are not.
 void setDisabledItemFilter(Filter<?> disabledItemFilter)
          Sets the disabled item filter.
 void setItemChecked(int index, boolean checked)
          Sets an item's checked state.
 void setItemEditor(ListView.ItemEditor itemEditor)
          Sets the editor used to edit items in this list.
 void setItemRenderer(ListView.ItemRenderer itemRenderer)
          Sets the item renderer to be used for items in this list.
 void setListData(List<?> listData)
          Sets the list data.
 void setListData(String listData)
          Sets the list data.
 void setListData(URL listData)
          Sets the list data.
 void setListDataBindMapping(ListView.ListDataBindMapping listDataBindMapping)
           
 void setListDataBindType(BindType listDataBindType)
           
 void setListDataKey(String listDataKey)
          Set the name of the key that is used in context binding.
 void setSelectedIndex(int index)
          Sets the selection to a single index.
 void setSelectedItem(Object item)
           
 void setSelectedItemBindMapping(ListView.ItemBindMapping selectedItemBindMapping)
           
 void setSelectedItemBindType(BindType selectedItemBindType)
           
 void setSelectedItemKey(String selectedItemKey)
           
 void setSelectedItems(Sequence<Object> items)
           
 void setSelectedItemsBindMapping(ListView.ItemBindMapping selectedItemsBindMapping)
           
 void setSelectedItemsBindType(BindType selectedItemsBindType)
           
 void setSelectedItemsKey(String selectedItemsKey)
           
 void setSelectedRange(int start, int end)
          Sets the selection to a single range.
 Sequence<Span> setSelectedRanges(Sequence<Span> selectedRanges)
          Sets the selection to the given range sequence.
 Sequence<Span> setSelectedRanges(String selectedRanges)
          Sets the selection to the given range sequence.
 void setSelectMode(ListView.SelectMode selectMode)
          Sets the selection mode.
protected  void setSkin(Skin skin)
          Sets the skin, replacing any previous skin.
 void store(Object context)
          Copies bound values from the component to the bind context.
 
Methods inherited from class org.apache.pivot.wtk.Component
clearFocus, contains, getAncestor, getAncestor, getAttribute, getAutomationID, getBaseline, getBaseline, getBounds, getComponentClassListeners, getComponentDataListeners, getComponentDecoratorListeners, getComponentKeyListeners, getComponentListeners, getComponentMouseButtonListeners, getComponentMouseListeners, getComponentMouseWheelListeners, getComponentStateListeners, getComponentStyleListeners, getComponentTooltipListeners, getCursor, getDecoratedBounds, getDecorators, getDisplay, getDragSource, getDropTarget, getFocusedComponent, getGraphics, getHeight, getHeightLimits, getLocation, getMaximumHeight, getMaximumWidth, getMenuHandler, getMinimumHeight, getMinimumWidth, getMouseLocation, getName, getNamedStyles, getParent, getPreferredHeight, getPreferredHeight, getPreferredSize, getPreferredWidth, getPreferredWidth, getSize, getSkin, getStyles, getTooltipDelay, getTooltipText, getTooltipWrapText, getTypedStyles, getUserData, getVisibleArea, getVisibleArea, getVisibleArea, getWidth, getWidthLimits, getWindow, getX, getY, indexBoundsCheck, installSkin, invalidate, isBlocked, isEnabled, isFocusable, isFocused, isMouseOver, isOpaque, isPreferredHeightSet, isPreferredSizeSet, isPreferredWidthSet, isShowing, isValid, isVisible, keyPressed, keyReleased, keyTyped, layout, mapPointFromAncestor, mapPointFromAncestor, mapPointToAncestor, mapPointToAncestor, mouseClick, mouseDown, mouseMove, mouseOut, mouseOver, mouseUp, mouseWheel, paint, reenterMouse, repaint, repaint, repaint, repaint, repaint, repaint, requestFocus, scrollAreaToVisible, scrollAreaToVisible, setAttribute, setAutomationID, setCursor, setDragSource, setDropTarget, setEnabled, setFocused, setHeight, setHeightLimits, setHeightLimits, setLocation, setLocation, setMaximumHeight, setMaximumWidth, setMenuHandler, setMinimumHeight, setMinimumWidth, setName, setParent, setPreferredHeight, setPreferredSize, setPreferredSize, setPreferredWidth, setSize, setSize, setStyleName, setStyleNames, setStyleNames, setStyles, setStyles, setTooltipDelay, setTooltipText, setTooltipWrapText, setVisible, setWidth, setWidthLimits, setWidthLimits, setX, setY, toString, transferFocus, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ListView

public ListView()
Creates a list view populated with an empty array list.


ListView

public ListView(List<?> listData)
Creates a list view populated with the given list data.

Note that the default renderer uses (as last option) the toString method on list elements, so override it to return whatever you want to display in the ListView, or implement your own custom renderer.

Parameters:
listData - The data to set.
See Also:
ListViewItemRenderer
Method Detail

getListData

public List<?> getListData()
Returns the list data.

Returns:
The data currently presented by the list view.

setListData

public void setListData(List<?> listData)
Sets the list data.

Parameters:
listData - The data to be presented by the list view.

setListData

public final void setListData(String listData)
Sets the list data.

Parameters:
listData - A JSON string (must begin with [ and end with ]) denoting the data to be presented by the list view.

setListData

public void setListData(URL listData)
Sets the list data.

Parameters:
listData - A URL referring to a JSON file containing the data to be presented by the list view.

setSkin

protected void setSkin(Skin skin)
Description copied from class: Component
Sets the skin, replacing any previous skin.

Overrides:
setSkin in class Component
Parameters:
skin - The new skin.

getItemRenderer

public ListView.ItemRenderer getItemRenderer()
Returns the item renderer used for items in this list.


setItemRenderer

public void setItemRenderer(ListView.ItemRenderer itemRenderer)
Sets the item renderer to be used for items in this list.

Parameters:
itemRenderer - The item renderer for the list.

getItemEditor

public ListView.ItemEditor getItemEditor()
Returns the editor used to edit items in this list.

Returns:
The item editor, or null if no editor is installed.

setItemEditor

public void setItemEditor(ListView.ItemEditor itemEditor)
Sets the editor used to edit items in this list.

Parameters:
itemEditor - The item editor for the list.

getSelectedIndex

public int getSelectedIndex()
Returns the currently selected index, even when in multi-select mode.

Returns:
The currently selected index.

setSelectedIndex

public void setSelectedIndex(int index)
Sets the selection to a single index.

Parameters:
index - The index to select, or -1 to clear the selection.

setSelectedRange

public void setSelectedRange(int start,
                             int end)
Sets the selection to a single range.

Parameters:
start -
end -

getSelectedRanges

public ImmutableList<Span> getSelectedRanges()
Returns the currently selected ranges.

Returns:
An immutable list containing the currently selected ranges. Note that the returned list is a wrapper around the actual selection, not a copy. Any changes made to the selection state will be reflected in the list, but events will not be fired.

setSelectedRanges

public Sequence<Span> setSelectedRanges(Sequence<Span> selectedRanges)
Sets the selection to the given range sequence. Any overlapping or connecting ranges will be consolidated, and the resulting selection will be sorted in ascending order.

Parameters:
selectedRanges -
Returns:
The ranges that were actually set.

setSelectedRanges

public final Sequence<Span> setSelectedRanges(String selectedRanges)
Sets the selection to the given range sequence.

Parameters:
selectedRanges - A JSON-formatted string containing the ranges to select.
Returns:
The ranges that were actually set.
Throws:
IllegalArgumentException - if the range string is null or if it can't be parsed as a JSON list.
See Also:
setSelectedRanges(Sequence)

getFirstSelectedIndex

public int getFirstSelectedIndex()
Returns the first selected index.

Returns:
The first selected index, or -1 if nothing is selected.

getLastSelectedIndex

public int getLastSelectedIndex()
Returns the last selected index.

Returns:
The last selected index, or -1 if nothing is selected.

addSelectedIndex

public boolean addSelectedIndex(int index)
Adds a single index to the selection.

Parameters:
index - The index to add.
Returns:
true if the index was added to the selection; false, otherwise.

addSelectedRange

public Sequence<Span> addSelectedRange(int start,
                                       int end)
Adds a range of indexes to the selection.

Parameters:
start - The first index in the range.
end - The last index in the range.
Returns:
The ranges that were added to the selection.
Throws:
IllegalStateException - if the ListView is not in multi-selection mode.

addSelectedRange

public Sequence<Span> addSelectedRange(Span range)
Adds a range of indexes to the selection.

Parameters:
range - The range to add.
Returns:
The ranges that were added to the selection.
Throws:
IllegalArgumentException - if the range is null.

removeSelectedIndex

public boolean removeSelectedIndex(int index)
Removes a single index from the selection.

Parameters:
index - The index to remove.
Returns:
true if the index was removed from the selection; false, otherwise.

removeSelectedRange

public Sequence<Span> removeSelectedRange(int start,
                                          int end)
Removes a range of indexes from the selection.

Parameters:
start - The start of the range to remove.
end - The end of the range to remove.
Returns:
The ranges that were removed from the selection.
Throws:
IllegalStateException - if the ListView is not in multi-selection mode.

removeSelectedRange

public Sequence<Span> removeSelectedRange(Span range)
Removes a range of indexes from the selection.

Parameters:
range - The range to remove.
Returns:
The ranges that were removed from the selection.

selectAll

public void selectAll()
Selects all items in the list.


clearSelection

public void clearSelection()
Clears the selection.


isItemSelected

public boolean isItemSelected(int index)
Returns the selection state of a given index.

Parameters:
index - The index whose selection state is to be tested.
Returns:
true if the index is selected; false, otherwise.

getSelectedItem

public Object getSelectedItem()

setSelectedItem

public void setSelectedItem(Object item)

getSelectedItems

public Sequence<?> getSelectedItems()

setSelectedItems

public void setSelectedItems(Sequence<Object> items)

getSelectMode

public ListView.SelectMode getSelectMode()
Returns the current selection mode.


setSelectMode

public void setSelectMode(ListView.SelectMode selectMode)
Sets the selection mode. Clears the selection if the mode has changed (but does not fire a selection change event).

Parameters:
selectMode - The new selection mode.

getCheckmarksEnabled

public boolean getCheckmarksEnabled()
Returns the current check mode.


setCheckmarksEnabled

public void setCheckmarksEnabled(boolean checkmarksEnabled)
Enables or disables checkmarks. Clears the check state if the check mode has changed (but does not fire any check state change events).

Parameters:
checkmarksEnabled - Whether checkmarks are enabled for each item.

isItemChecked

public boolean isItemChecked(int index)
Returns an item's checked state.

Parameters:
index - Index of item to interrogate.

setItemChecked

public void setItemChecked(int index,
                           boolean checked)
Sets an item's checked state.

Parameters:
index - Index of item.
checked - New value for the item's checked state.
Throws:
IllegalStateException - if checkmarks are not enabled.

getCheckedIndexes

public ImmutableList<Integer> getCheckedIndexes()
Returns the indexes of currently checked items.


clearCheckmarks

public void clearCheckmarks()
Clears the checked state of all checked items.


isCheckmarkDisabled

public boolean isCheckmarkDisabled(int index)
Tells whether or not an item's checkmark is disabled. Queries the current disabled checkmark filter (if any).

Parameters:
index - The index of the item whose disabled checkmark state is to be tested.
Returns:
true if the item's checkmark is disabled; false otherwise (such as if no disabled checkmark filter is set).

getDisabledCheckmarkFilter

public Filter<?> getDisabledCheckmarkFilter()
Returns the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; items may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

Note: this filter is only relevant if checkmarksEnabled is set to true.

Returns:
The disabled checkmark filter, or null if no disabled checkmark filter is set

setDisabledCheckmarkFilter

public void setDisabledCheckmarkFilter(Filter<?> disabledCheckmarkFilter)
Sets the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; items may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

Note: this filter is only relavent if checkmarksEnabled is set to true. enabled.

Parameters:
disabledCheckmarkFilter - The disabled checkmark filter, or null for no disabled checkmark filter

isItemDisabled

public boolean isItemDisabled(int index)
Returns an item's disabled state.

Parameters:
index - The index of the item whose disabled state is to be tested.
Returns:
true if the item is disabled; false, otherwise.

getDisabledItemFilter

public Filter<?> getDisabledItemFilter()
Returns the disabled item filter.

Returns:
The disabled item filter, or null if no disabled item filter is set.

setDisabledItemFilter

public void setDisabledItemFilter(Filter<?> disabledItemFilter)
Sets the disabled item filter.

Parameters:
disabledItemFilter - The disabled item filter, or null for no disabled item filter.

getListDataKey

public String getListDataKey()
Returns name of the key that is used in context binding.

Returns:
The key.

setListDataKey

public void setListDataKey(String listDataKey)
Set the name of the key that is used in context binding.

Parameters:
listDataKey - The key to set.

getListDataBindType

public BindType getListDataBindType()

setListDataBindType

public void setListDataBindType(BindType listDataBindType)

getListDataBindMapping

public ListView.ListDataBindMapping getListDataBindMapping()

setListDataBindMapping

public void setListDataBindMapping(ListView.ListDataBindMapping listDataBindMapping)

getSelectedItemKey

public String getSelectedItemKey()

setSelectedItemKey

public void setSelectedItemKey(String selectedItemKey)

getSelectedItemBindType

public BindType getSelectedItemBindType()

setSelectedItemBindType

public void setSelectedItemBindType(BindType selectedItemBindType)

getSelectedItemBindMapping

public ListView.ItemBindMapping getSelectedItemBindMapping()

setSelectedItemBindMapping

public void setSelectedItemBindMapping(ListView.ItemBindMapping selectedItemBindMapping)

getSelectedItemsKey

public String getSelectedItemsKey()

setSelectedItemsKey

public void setSelectedItemsKey(String selectedItemsKey)

getSelectedItemsBindType

public BindType getSelectedItemsBindType()

setSelectedItemsBindType

public void setSelectedItemsBindType(BindType selectedItemsBindType)

getSelectedItemsBindMapping

public ListView.ItemBindMapping getSelectedItemsBindMapping()

setSelectedItemsBindMapping

public void setSelectedItemsBindMapping(ListView.ItemBindMapping selectedItemsBindMapping)

getCheckedItemsKey

public String getCheckedItemsKey()

setCheckedItemsKey

public void setCheckedItemsKey(String checkedItemsKey)

getCheckedItemsBindType

public BindType getCheckedItemsBindType()

setCheckedItemsBindType

public void setCheckedItemsBindType(BindType checkedItemsBindType)

getCheckedItemsBindMapping

public ListView.ItemBindMapping getCheckedItemsBindMapping()

setCheckedItemsBindMapping

public void setCheckedItemsBindMapping(ListView.ItemBindMapping checkedItemsBindMapping)

load

public void load(Object context)
Description copied from class: Component
Copies bound values from the bind context to the component. This functionality must be provided by the subclass; the base implementation is a no-op.

Overrides:
load in class Component

store

public void store(Object context)
Description copied from class: Component
Copies bound values from the component to the bind context. This functionality must be provided by the subclass; the base implementation is a no-op.

Overrides:
store in class Component

clear

public void clear()
Description copied from class: Component
Clears any bound values in the component.

Overrides:
clear in class Component

getItemAt

public int getItemAt(int y)
Returns the index of the item at a given location.

Parameters:
y - The y-coordinate of the item to identify.
Returns:
The item index, or -1 if there is no item at the given y-coordinate.

getItemBounds

public Bounds getItemBounds(int index)
Returns the bounding area of a given item.

Parameters:
index - The item index.
Returns:
The bounding area of the item.

getItemIndent

public int getItemIndent()
Returns the item indent.

Returns:
The horizontal space preceding items in the list.

getListViewListeners

public ListenerList<ListViewListener> getListViewListeners()
Returns the list view listener list.


getListViewItemListeners

public ListenerList<ListViewItemListener> getListViewItemListeners()
Returns the list view item listener list.


getListViewItemStateListeners

public ListenerList<ListViewItemStateListener> getListViewItemStateListeners()
Returns the list view item state listener list.


getListViewSelectionListeners

public ListenerList<ListViewSelectionListener> getListViewSelectionListeners()
Returns the list view selection detail listener list.


getListViewBindingListeners

public ListenerList<ListViewBindingListener> getListViewBindingListeners()