Package 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 Details

    • 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 Details

    • 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:

    • 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
      invalid @code 
      {@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.