com.explodingpixels.macwidgets

Class SourceList

java.lang.Object

com.explodingpixels.macwidgets.SourceList

public class SourceList
extends Object

An implementation of an OS X Source List. For a full descrption of what a Source List is, see the Source Lists section of Apple's Human Interface Guidelines.

This component provides the two basic sytles of Source List: focusble and non-focusable. As the name implies, focusable Source Lists and recieve keyboard focus, and thus can be navigated using the arrow keys. Non-focusable, cannot receive keyboard focus, and thus cannot be navigated via the arrow keys. The two styles of SourceList are pictured below:

Focusable SourceList	Non-focusable SourceList

Here's how to create a simple SourceList with one item:

 SourceListModel model = new SourceListModel();
 SourceListCategory category = new SourceListCategory("Category");
 model.addCategory(category);
 model.addItemToCategory(new SourceListItem("Item"), category);
 SourceList sourceList = new SourceList(model);
 

To install a selection listener on the SourceList, add a SourceListSelectionListener.

To install a context-menu provider, call setSourceListContextMenuProvider(SourceListContextMenuProvider) with an implementation of SourceListContextMenuProvider.

Constructor Summary

Constructors

Constructor and Description
SourceList() Creates a SourceList with an empty SourceListModel.
SourceList(SourceListModel model) Creates a SourceList with the given SourceListModel.

Method Summary

Methods

Modifier and Type	Method and Description
void	addSourceListClickListener(SourceListClickListener listener) Adds the SourceListClickListener to the list of listeners.
void	addSourceListSelectionListener(SourceListSelectionListener listener) Adds the SourceListSelectionListener to the list of listeners.
void	clearSelection() Clears the current selection, if there is one.
void	dispose() Uninstalls any listeners that this SourceList installed on creation, thereby allowing it to be garbage collected.
SourceListColorScheme	getColorScheme() Gets the SourceListColorScheme that this SourceList uses.
JComponent	getComponent() Gets the user interface component representing this SourceList.
SourceListModel	getModel() Gets the SourceListModel backing this SourceList.
SourceListItem	getSelectedItem() Gets the selected SourceListItem.
void	installSourceListControlBar(SourceListControlBar sourceListControlBar) Installs the given SourceListControlBar at the base of this SourceList.
boolean	isSourceListControlBarInstalled() True if there is a SourceListControlBar installed on this SourceList.
void	removeSourceListClickListener(SourceListClickListener listener) Removes the SourceListClickListener to the list of listeners.
void	removeSourceListSelectionListener(SourceListSelectionListener listener) Removes the SourceListSelectionListener from the list of listeners.
void	scrollItemToVisible(SourceListItem item) Scrolls the given SourceListItem to be visible.
void	setColorScheme(SourceListColorScheme colorScheme) Sets the SourceListColorScheme that this SourceList uses.
void	setExpanded(SourceListCategory category, boolean expanded) Sets the expanded state of the given SourceListCategory.
void	setExpanded(SourceListItem item, boolean expanded) Sets the expanded state of the given SourceListItem.
void	setFocusable(boolean focusable) Sets whether this SourceList can have focus.
void	setSelectedItem(SourceListItem item) Selects the given SourceListItem in the list.
void	setSourceListContextMenuProvider(SourceListContextMenuProvider contextMenuProvider) Sets the SourceListContextMenuProvider to use for this SourceList.
void	setToolTipProvider(SourceListToolTipProvider toolTipProvider) Sets the SourceListToolTipProvider to use.
void	setTransferHandler(TransferHandler transferHandler) Set's the TransferHandler that this SourceList should use during drag and drop operations.
void	useIAppStyleScrollBars() Installs iApp style scroll bars on this SourceList.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SourceList

public SourceList()

Creates a SourceList with an empty SourceListModel.

SourceList

public SourceList(SourceListModel model)

Creates a SourceList with the given SourceListModel.

Parameters:

model - the SourceListModel to use.

Method Detail

installSourceListControlBar

public void installSourceListControlBar(SourceListControlBar sourceListControlBar)

Installs the given SourceListControlBar at the base of this SourceList. This method can be called only once, and should generally be called during creation of the SourceList.

Parameters:

sourceListControlBar - the SourceListControlBar to add.

Throws:

IllegalStateException - if a SourceListControlBar has already been installed on this SourceList.

IllegalArgumentException - if the SourceListControlBar is null.

isSourceListControlBarInstalled

public boolean isSourceListControlBarInstalled()

True if there is a SourceListControlBar installed on this SourceList.

Returns:

true if there is a SourceListControlBar installed on this SourceList.

setSourceListContextMenuProvider

public void setSourceListContextMenuProvider(SourceListContextMenuProvider contextMenuProvider)

Sets the SourceListContextMenuProvider to use for this SourceList.

Parameters:

contextMenuProvider - the SourceListContextMenuProvider to use for this SourceList.

Throws:

IllegalArgumentException - if the SourceListContextMenuProvider is null.

dispose

public void dispose()

Uninstalls any listeners that this SourceList installed on creation, thereby allowing it to be garbage collected.

getSelectedItem

public SourceListItem getSelectedItem()

Gets the selected SourceListItem.

Returns:

the selected SourceListItem.

setSelectedItem

public void setSelectedItem(SourceListItem item)

Selects the given SourceListItem in the list.

Parameters:

item - the item to select.

Throws:

IllegalArgumentException - if the given item is not in the list.

clearSelection

public void clearSelection()

Clears the current selection, if there is one.

setFocusable

public void setFocusable(boolean focusable)

Sets whether this SourceList can have focus. When focusable and this SourceList has focus, the keyboard can be used for navigation.

Parameters:

focusable - true if this SourceList should be focusable.

useIAppStyleScrollBars

public void useIAppStyleScrollBars()

Installs iApp style scroll bars on this SourceList.

See Also:

IAppWidgetFactory.makeIAppScrollPane(javax.swing.JScrollPane)

getColorScheme

public SourceListColorScheme getColorScheme()

Gets the SourceListColorScheme that this SourceList uses.

Returns:

the SourceListColorScheme that this SourceList uses.

setColorScheme

public void setColorScheme(SourceListColorScheme colorScheme)

Sets the SourceListColorScheme that this SourceList uses.

Parameters:

colorScheme - the SourceListColorScheme that this SourceList uses.

setTransferHandler

public void setTransferHandler(TransferHandler transferHandler)

Set's the TransferHandler that this SourceList should use during drag and drop operations. If the given handler not null, then dragging will be turned on for the SourceList. If the handler is null, then dragging will be turned off.

Parameters:

transferHandler - the TransferHandler for this SourceList. Can be null.

scrollItemToVisible

public void scrollItemToVisible(SourceListItem item)

Scrolls the given SourceListItem to be visible.

Parameters:

item - the SourceListItem to scroll to visible.

setExpanded

public void setExpanded(SourceListCategory category,
               boolean expanded)

Sets the expanded state of the given SourceListCategory.

Parameters:

category - the category to set the expanded state on.

expanded - true if the given category should be expanded, false if it should be collapsed.

Throws:

IllegalArgumentException - if the given SourceListCategory is not part of the associated SourceListModel.

setExpanded

public void setExpanded(SourceListItem item,
               boolean expanded)

Sets the expanded state of the given SourceListItem.

Parameters:

item - the item to set the expanded state on.

expanded - true if the given item should be expanded, false if it should be collapsed.

Throws:

IllegalArgumentException - if the given SourceListItem is not part of the associated SourceListModel.

getComponent

public JComponent getComponent()

Gets the user interface component representing this SourceList. The returned JComponent should be added to a container that will be displayed.

Returns:

the user interface component representing this SourceList.

getModel

public SourceListModel getModel()

Gets the SourceListModel backing this SourceList.

Returns:

the SourceListModel backing this SourceList.

setToolTipProvider

public void setToolTipProvider(SourceListToolTipProvider toolTipProvider)

Sets the SourceListToolTipProvider to use.

Parameters:

toolTipProvider - the {@code SourceListToolTipProvider to use.

addSourceListClickListener

public void addSourceListClickListener(SourceListClickListener listener)

Adds the SourceListClickListener to the list of listeners.

Parameters:

listener - the SourceListClickListener to add.

removeSourceListClickListener

public void removeSourceListClickListener(SourceListClickListener listener)

Removes the SourceListClickListener to the list of listeners.

Parameters:

listener - the SourceListClickListener to remove.

addSourceListSelectionListener

public void addSourceListSelectionListener(SourceListSelectionListener listener)

Adds the SourceListSelectionListener to the list of listeners.

Parameters:

listener - the SourceListSelectionListener to add.

removeSourceListSelectionListener

public void removeSourceListSelectionListener(SourceListSelectionListener listener)

Removes the SourceListSelectionListener from the list of listeners.

Parameters:

listener - the SourceListSelectionListener to remove.