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` | `addSourceListExpansionListener(SourceListExpansionListener listener)` Adds the `SourceListExpansionListener` 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` | `removeSourceListExpansionListener(SourceListExpansionListener listener)` Removes the `SourceListExpansionListener` from 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.

    - #### addSourceListExpansionListener

          public void addSourceListExpansionListener(SourceListExpansionListener listener)

      Adds the `SourceListExpansionListener` to the list of listeners.
      Parameters:
        `listener` - the `SourceListExpansionListener` to add.

    - #### removeSourceListExpansionListener

          public void removeSourceListExpansionListener(SourceListExpansionListener listener)

      Removes the `SourceListExpansionListener` from the list of listeners.
      Parameters:
        `listener` - the `SourceListExpansionListener` to remove.