Class JList

public static final int HORIZONTAL_WRAP

Constant value used in "layoutOrientation" property. This value means that cells are laid out in multiple columns "newspaper style", filling horizontally first, then vertically.

Field Value:

2

public static final int VERTICAL

Constant value used in "layoutOrientation" property. This value means that cells are laid out in a single vertical column. This is the default.

Field Value:

0

public static final int VERTICAL_WRAP

Constant value used in "layoutOrientation" property. This value means that cells are laid out in multiple columns "newspaper style", filling vertically first, then horizontally.

Field Value:

1

public JList()

Creates a new JList object.

public JList(Vector items)

Creates a new JList object.

Parameters:

items - the initial list items.

public JList(Object[] items)

Creates a new JList object.

Parameters:

items - the initial list items.

public JList(ListModel model)

Creates a new JList object.

Parameters:

model - a model containing the list items (null not permitted).

Throws:

IllegalArgumentException - if model is null.

public void addListSelectionListener(ListSelectionListener listener)

Adds a ListSelectionListener to the listener list for this list. The listener will be called back with a ListSelectionEvent any time the list's selectionModel property changes. The source of such events will be the JList, not the selection model.

Parameters:

listener - The new listener to add

public void addSelectionInterval(int anchor,
                                 int lead)

Adds the specified interval to the current selection. Note that anchor can be less than, equal to, or greater than lead.

Parameters:

anchor - the index of the anchor item.

lead - the index of the lead item.

public void clearSelection()

Clears the current selection.

protected ListSelectionModel createSelectionModel()

Creates the default ListSelectionModel.

Returns:

the ListSelectionModel

public void ensureIndexIsVisible(int i)

Scrolls this list to make the specified cell visible. This only works if the list is contained within a viewport.

Parameters:

i - The list index to make visible

See Also:

JComponent.scrollRectToVisible(Rectangle)

protected void fireSelectionValueChanged(int firstIndex,
                                         int lastIndex,
                                         boolean isAdjusting)

Fire a ListSelectionEvent to all the registered ListSelectionListeners.

Parameters:

firstIndex - the lowest index covering the selection change.

lastIndex - the highest index covering the selection change.

isAdjusting - a flag indicating if this event is one in a series of events updating the selection.

public AccessibleContext getAccessibleContext()

Returns the accessibility framework context of this class. Component is not accessible, so the default implementation returns null. Subclasses must override this behavior, and return an appropriate subclass of Component.AccessibleAWTComponent.

Specified by:

getAccessibleContext in interface Accessible

Overrides:

getAccessibleContext in interface JComponent

Returns:

the accessibility context

public int getAnchorSelectionIndex()

Returns the index of the anchor item in the current selection, or -1 if there is no anchor item.

Returns:

The item index.

public Rectangle getCellBounds(int index0,
                               int index1)

Returns the bounds of the rectangle that encloses both list cells with index0 and index1.

Parameters:

index0 - the index of the first cell

index1 - the index of the second cell

Returns:

the bounds of the rectangle that encloses both list cells with index0 and index1, null if one of the indices is not valid

public ListCellRenderer getCellRenderer()

Gets the value of the cellRenderer property.

Returns:

The current value of the property

public boolean getDragEnabled()

Return the value of the dragEnabled property.

Returns:

the value

Since:

1.4

public int getFirstVisibleIndex()

Returns the list index of the upper left or upper right corner of the visible rectangle of this list, depending on the Component.getComponentOrientation() property.

Returns:

The index of the first visible list cell, or -1 if none is visible.

public int getFixedCellHeight()

Gets the value of the fixedCellHeight property. This property may be -1 to indicate that no cell height has been set. This property is also set implicitly when the prototypeCellValue property is set.

Returns:

The current value of the property

See Also:

fixedCellHeight, setFixedCellHeight(int), setPrototypeCellValue(Object)

public int getFixedCellWidth()

Gets the value of the fixedCellWidth property. This property may be -1 to indicate that no cell width has been set. This property is also set implicitly when the prototypeCellValue property is set.

Returns:

The current value of the property

See Also:

setFixedCellWidth(int), setPrototypeCellValue(Object)

public int getLastVisibleIndex()

Returns the list index of the lower right or lower left corner of the visible rectangle of this list, depending on the Component.getComponentOrientation() property.

Returns:

The index of the last visible list cell, or -1 if none is visible.

public int getLayoutOrientation()

Returns the layout orientation, which will be one of VERTICAL, VERTICAL_WRAP and HORIZONTAL_WRAP. The default value is VERTICAL.

Returns:

the orientation.

Since:

1.4

See Also:

setLayoutOrientation(int)

public int getLeadSelectionIndex()

Returns the index of the lead item in the current selection, or -1 if there is no lead item.

Returns:

The item index.

public ListSelectionListener[] getListSelectionListeners()

Returns an array of all ListSelectionListeners subscribed to this list.

Returns:

The current subscribed listeners

Since:

1.4

public int getMaxSelectionIndex()

Returns the highest item index in the current selection, or -1 if there is no selection.

Returns:

The index.

See Also:

getMinSelectionIndex()

public int getMinSelectionIndex()

Returns the lowest item index in the current selection, or -1 if there is no selection.

Returns:

The index.

See Also:

getMaxSelectionIndex()

public ListModel getModel()

Gets the value of the model property.

Returns:

The current value of the property

public int getNextMatch(String prefix,
                        int startIndex,
                        Position.Bias direction)

Returns the index of the next list element (beginning at startIndex and moving in the specified direction through the list, looping around if necessary) that starts with prefix (ignoring case).

Parameters:

prefix - the prefix to search for in the cell values

startIndex - the index where to start searching from

direction - the search direction, either Position.Bias.Forward or Position.Bias.Backward (null is interpreted as Position.Bias.Backward.

Returns:

the index of the found element or -1 if no such element has been found

Throws:

IllegalArgumentException - if prefix is null or startIndex is not valid

Since:

1.4

public Dimension getPreferredScrollableViewportSize()

Returns a size indicating how much space this list would like to consume, when contained in a scrollable viewport. This is part of the Scrollable interface, which interacts with ScrollPaneLayout and JViewport to define scrollable objects.

Specified by:

getPreferredScrollableViewportSize in interface Scrollable

Returns:

The preferred size

public Object getPrototypeCellValue()

Returns the current value of the prototypeCellValue property. This property holds a reference to a "prototype" data value -- typically a String -- which is used to calculate the fixedCellWidth and fixedCellHeight properties, using the cellRenderer property to acquire a component to render the prototype.

Returns:

The current prototype cell value

See Also:

setPrototypeCellValue(Object)

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)

Return the number of pixels the list must scroll in order to move a "block" of the list into the provided visible rectangle. When the provided direction is positive, the call describes a "downwards" scroll, which will be exposing a cell at a greater index in the list than those elements currently showing. Then the provided direction is negative, the call describes an "upwards" scroll, which will be exposing a cell at a lesser index in the list than those elements currently showing.

If the provided orientation is HORIZONTAL, the above comments refer to "rightwards" for positive direction, and "leftwards" for negative.

Specified by:

getScrollableBlockIncrement in interface Scrollable

Parameters:

visibleRect - The rectangle to scroll an element into

orientation - One of the numeric consants VERTICAL or HORIZONTAL

direction - An integer indicating the scroll direction: positive means forwards (down, right), negative means backwards (up, left)

Returns:

The scrollable unit increment, in pixels

public boolean getScrollableTracksViewportHeight()

Gets the value of the scrollableTracksViewportWidth property.

Specified by:

getScrollableTracksViewportHeight in interface Scrollable

Returns:

true if the viewport is larger (vertically) than the list and the list should be expanded to fit the viewport; false if the viewport is smaller than the list and the list should scroll (vertically) within the viewport

public boolean getScrollableTracksViewportWidth()

Gets the value of the scrollableTracksViewportWidth property.

Specified by:

getScrollableTracksViewportWidth in interface Scrollable

Returns:

true if the viewport is larger (horizontally) than the list and the list should be expanded to fit the viewport; false if the viewport is smaller than the list and the list should scroll (horizontally) within the viewport

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)

Return the number of pixels the list must scroll in order to move a "unit" of the list into the provided visible rectangle. When the provided direction is positive, the call describes a "downwards" scroll, which will be exposing a cell at a greater index in the list than those elements currently showing. Then the provided direction is negative, the call describes an "upwards" scroll, which will be exposing a cell at a lesser index in the list than those elements currently showing.

If the provided orientation is HORIZONTAL, the above comments refer to "rightwards" for positive direction, and "leftwards" for negative.

Specified by:

getScrollableUnitIncrement in interface Scrollable

Parameters:

visibleRect - The rectangle to scroll an element into

orientation - One of the numeric consants VERTICAL or HORIZONTAL

direction - An integer indicating the scroll direction: positive means forwards (down, right), negative means backwards (up, left)

Returns:

The scrollable unit increment, in pixels

public int getSelectedIndex()

Returns the minimum index of an element in the list which is currently selected.

Returns:

A number in the half-open range [0, x) where x = getModel.getSize(), indicating the minimum index of an element in the list for which the element is selected, or -1 if no elements are selected

public int[] getSelectedIndices()

Returns the indices of values in the model property which are selected.

Returns:

An array of model indices, each of which is selected according to the getSelectedValues() property

public Object getSelectedValue()

Returns the first value in the list's model property which is selected, according to the list's selectionModel property. This is equivalent to calling getModel()getElementAt(getSelectedIndex()), with a check for the special index value of -1 which returns null null.

Returns:

The first selected element, or null if no element is selected.

See Also:

getSelectedValues()

public Object[] getSelectedValues()

Returns all the values in the list's model property which are selected, according to the list's selectionModel property.

Returns:

An array containing all the selected values

See Also:

setSelectedValue(Object,boolean)

public Color getSelectionBackground()

Gets the value of the selectionBackground property.

Returns:

The current value of the property

public Color getSelectionForeground()

Gets the value of the selectionForeground property.

Returns:

The current value of the property

public int getSelectionMode()

Returns the selection mode for the list (one of: ListSelectionModel.SINGLE_SELECTION, ListSelectionModel.SINGLE_INTERVAL_SELECTION and ListSelectionModel.MULTIPLE_INTERVAL_SELECTION).

Returns:

The selection mode.

See Also:

setSelectionMode(int)

public ListSelectionModel getSelectionModel()

Returns the selection model for the JList component. Note that this class contains a range of convenience methods for configuring the selection model:

• clearSelection();
• setSelectionMode(int);
• addSelectionInterval(int,int);
• setSelectedIndex(int);
• setSelectedIndices(int[]);
• setSelectionInterval(int,int).

Returns:

The selection model.

public ListUI getUI()

Gets the value of the UI property.

Returns:

The current property value

public String getUIClassID()

Return the class identifier for the list's UI property. This should be the constant string "ListUI", and map to an appropriate UI class in the UIManager.

Overrides:

getUIClassID in interface JComponent

Returns:

The class identifier

public boolean getValueIsAdjusting()

Returns the valueIsAdjusting flag from the list's selection model.

Returns:

the value

public int getVisibleRowCount()

Gets the value of the visibleRowCount property. The default value is 8.

Returns:

the current value of the property.

See Also:

setVisibleRowCount(int)

public Point indexToLocation(int index)

Returns location of the cell located at the specified index in the list.

Parameters:

index - of the cell for which location will be determined

Returns:

location of the cell located at the specified index in the list.

public boolean isSelectedIndex(int a)

Indicates whether the list element at a given index value is currently selected.

Parameters:

a - The index to check

Returns:

true if a is the index of a selected list element

public boolean isSelectionEmpty()

Returns true if the model's selection is empty, otherwise false.

Returns:

The return value of ListSelectionModel.isSelectionEmpty()

public int locationToIndex(Point location)

Returns index of the cell to which specified location is closest to. If the location is outside the bounds of the list, then the greatest index in the list model is returned. If the list model is empty, then -1 is returned.

Parameters:

location - for which to look for in the list

Returns:

index of the cell to which specified location is closest to.

protected String paramString()

Returns a string describing the attributes for the JList component, for use in debugging. The return value is guaranteed to be non-null, but the format of the string may vary between implementations.

Overrides:

paramString in interface JComponent

Returns:

A string describing the attributes of the JList.

public void removeListSelectionListener(ListSelectionListener listener)

Removes a ListSelectionListener from the listener list for this list. The listener will no longer be called when the list's selectionModel changes.

Parameters:

listener - The listener to remove

public void removeSelectionInterval(int index0,
                                    int index1)

Removes the specified interval from the current selection. Note that index0 can be less than, equal to, or greater than index1.

Parameters:

index0 - an index for one end of the range.

index1 - an index for the other end of the range.

public void setCellRenderer(ListCellRenderer renderer)

Sets the value of the getCellRenderer() property.

Parameters:

renderer - The new property value

public void setDragEnabled(boolean enabled)

Set the dragEnabled property.

Parameters:

enabled - new value

Since:

1.4

public void setFixedCellHeight(int h)

Sets the value of the fixedCellHeight property. This property may be -1 to indicate that no cell height has been set. This property is also set implicitly when the prototypeCellValue property is set, but setting it explicitly overrides the height computed from prototypeCellValue.

Parameters:

h - the height.

See Also:

getFixedCellHeight(), getPrototypeCellValue()

public void setFixedCellWidth(int w)

Sets the value of the fixedCellWidth property. This property may be -1 to indicate that no cell width has been set. This property is also set implicitly when the prototypeCellValue property is set, but setting it explicitly overrides the width computed from prototypeCellValue.

Parameters:

w - the width.

See Also:

getFixedCellHeight(), getPrototypeCellValue()

public void setLayoutOrientation(int orientation)

Sets the layout orientation (this is a bound property with the name 'layoutOrientation'). Valid orientations are VERTICAL, VERTICAL_WRAP and HORIZONTAL_WRAP.

Parameters:

orientation - the orientation.

Throws:

IllegalArgumentException - if orientation is not one of the specified values.

Since:

1.4

See Also:

getLayoutOrientation()

public void setListData(Vector listData)

Sets the model property of the list to a new anonymous AbstractListModel subclass which accesses the provided vector directly.

Parameters:

listData - The object array to build a new list model on

See Also:

setModel(ListModel)

public void setListData(Object[] listData)

Sets the model property of the list to a new anonymous AbstractListModel subclass which accesses the provided Object array directly.

Parameters:

listData - The object array to build a new list model on

See Also:

setModel(ListModel)

public void setModel(ListModel model)

Sets the value of the model property. The list's listListener is unsubscribed from the existing model, if it exists, and re-subscribed to the new model.

Parameters:

model - the new model (null not permitted).

Throws:

IllegalArgumentException - if model is null.

public void setPrototypeCellValue(Object obj)

Set the prototypeCellValue property. This property holds a reference to a "prototype" data value -- typically a String -- which is used to calculate the fixedCellWidth and fixedCellHeight properties, using the cellRenderer property to acquire a component to render the prototype.

It is important that you not set this value to a component. It has to be a data value such as the objects you would find in the list's model. Setting it to a component will have undefined (and undesirable) affects.

Parameters:

obj - The new prototype cell value

See Also:

getPrototypeCellValue()

public void setSelectedIndex(int a)

Adds the interval [a,a] to the set of selections managed by this list's selectionModel property. Depending on the selection mode, this may cause existing selections to become invalid, or may simply expand the set of selections.

Parameters:

a - A number in the half-open range [0, x) where x = getModel.getSize(), indicating the index of an element in the list to select. When < 0 the selection is cleared.

See Also:

setSelectionMode(int), selectionModel

public void setSelectedIndices(int[] a)

For each element a[i] of the provided array a, calls setSelectedIndex(int) on a[i].

Parameters:

a - an array of selected indices (null not permitted).

Throws:

NullPointerException - if a is null.

See Also:

setSelectionMode(int), selectionModel

public void setSelectedValue(Object obj,
                             boolean scroll)

Sets the selection to cover only the specified value, if it exists in the model.

Parameters:

obj - The object to select

scroll - Whether to scroll the list to make the newly selected value visible

See Also:

ensureIndexIsVisible(int)

public void setSelectionBackground(Color c)

Sets the value of the selectionBackground property.

Parameters:

c - The new value of the property

public void setSelectionForeground(Color c)

Sets the value of the selectionForeground property.

Parameters:

c - The new value of the property

public void setSelectionInterval(int anchor,
                                 int lead)

Sets the current selection to the items in the specified range (inclusive). Note that anchor can be less than, equal to, or greater than lead.

Parameters:

anchor - the index of the anchor item.

lead - the index of the anchor item.

public void setSelectionMode(int a)

Sets the list's "selectionMode" property, which simply mirrors the same property on the list's selectionModel property. This property should be one of the integer constants SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION, or MULTIPLE_INTERVAL_SELECTION from the ListSelectionModel interface.

Parameters:

a - The new selection mode

public void setSelectionModel(ListSelectionModel model)

Sets the value of the selectionModel property. The list's listListener is unsubscribed from the existing selection model, if it exists, and re-subscribed to the new selection model.

Parameters:

model - The new property value

public void setUI(ListUI ui)

Sets the value of the UI property.

Parameters:

ui - The new property value

public void setValueIsAdjusting(boolean isAdjusting)

Sets the valueIsAdjusting flag in the list's selection model.

Parameters:

isAdjusting - the new value

public void setVisibleRowCount(int vc)

Sets the value of the visibleRowCount property.

Parameters:

vc - The new property value

See Also:

getVisibleRowCount()

public void updateUI()

Calls setUI(ListUI) with the ListUI subclass returned from calling UIManager.getUI(JComponent).

Overrides:

updateUI in interface JComponent