Package com.explodingpixels.macwidgets

Class SourceList

  • public class SourceList
extends java.lang.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 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:
        java.lang.IllegalStateException - if a SourceListControlBar has already been installed on this SourceList.
        java.lang.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.

      • dispose

        public void dispose()
        Uninstalls any listeners that this SourceList installed on creation, thereby allowing it to be garbage collected.

      • setSelectedItem

        public void setSelectedItem​(SourceListItem item)
        Selects the given SourceListItem in the list.
        Parameters:
        item - the item to select.
        Throws:
        java.lang.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.

      • setTransferHandler

        public void setTransferHandler​(javax.swing.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if the given SourceListItem is not part of the associated SourceListModel.

      • getComponent

        public javax.swing.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.

      • removeSourceListClickListener

        public void removeSourceListClickListener​(SourceListClickListener listener)
        Removes the SourceListClickListener to the list of listeners.
        Parameters:
        listener - the SourceListClickListener to remove.