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
`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.