Package com.explodingpixels.macwidgets
Class SourceList
- java.lang.Object
-
- com.explodingpixels.macwidgets.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 ofSourceList
are pictured below:
Focusable SourceList Non-focusable SourceList
Here's how to create a simpleSourceList
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
To install a context-menu provider, callSourceList
, add aSourceListSelectionListener
.setSourceListContextMenuProvider(SourceListContextMenuProvider)
with an implementation ofSourceListContextMenuProvider
.
-
-
Constructor Summary
Constructors Constructor Description SourceList()
Creates aSourceList
with an emptySourceListModel
.SourceList(SourceListModel model)
Creates aSourceList
with the givenSourceListModel
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addSourceListClickListener(SourceListClickListener listener)
Adds theSourceListClickListener
to the list of listeners.void
addSourceListExpansionListener(SourceListExpansionListener listener)
Adds theSourceListExpansionListener
to the list of listeners.void
addSourceListSelectionListener(SourceListSelectionListener listener)
Adds theSourceListSelectionListener
to the list of listeners.void
clearSelection()
Clears the current selection, if there is one.void
dispose()
Uninstalls any listeners that thisSourceList
installed on creation, thereby allowing it to be garbage collected.SourceListColorScheme
getColorScheme()
Gets theSourceListColorScheme
that thisSourceList
uses.javax.swing.JComponent
getComponent()
Gets the user interface component representing thisSourceList
.SourceListModel
getModel()
Gets theSourceListModel
backing thisSourceList
.SourceListItem
getSelectedItem()
Gets the selectedSourceListItem
.void
installSourceListControlBar(SourceListControlBar sourceListControlBar)
Installs the givenSourceListControlBar
at the base of thisSourceList
.boolean
isSourceListControlBarInstalled()
True if there is aSourceListControlBar
installed on thisSourceList
.void
removeSourceListClickListener(SourceListClickListener listener)
Removes theSourceListClickListener
to the list of listeners.void
removeSourceListExpansionListener(SourceListExpansionListener listener)
Removes theSourceListExpansionListener
from the list of listeners.void
removeSourceListSelectionListener(SourceListSelectionListener listener)
Removes theSourceListSelectionListener
from the list of listeners.void
scrollItemToVisible(SourceListItem item)
Scrolls the givenSourceListItem
to be visible.void
setColorScheme(SourceListColorScheme colorScheme)
Sets theSourceListColorScheme
that thisSourceList
uses.void
setExpanded(SourceListCategory category, boolean expanded)
Sets the expanded state of the givenSourceListCategory
.void
setExpanded(SourceListItem item, boolean expanded)
Sets the expanded state of the givenSourceListItem
.void
setFocusable(boolean focusable)
Sets whether thisSourceList
can have focus.void
setSelectedItem(SourceListItem item)
Selects the givenSourceListItem
in the list.void
setSourceListContextMenuProvider(SourceListContextMenuProvider contextMenuProvider)
Sets theSourceListContextMenuProvider
to use for thisSourceList
.void
setToolTipProvider(SourceListToolTipProvider toolTipProvider)
Sets theSourceListToolTipProvider
to use.void
setTransferHandler(javax.swing.TransferHandler transferHandler)
Set's theTransferHandler
that thisSourceList
should use during drag and drop operations.void
useIAppStyleScrollBars()
Installs iApp style scroll bars on thisSourceList
.
-
-
-
Constructor Detail
-
SourceList
public SourceList()
Creates aSourceList
with an emptySourceListModel
.
-
SourceList
public SourceList(SourceListModel model)
Creates aSourceList
with the givenSourceListModel
.- Parameters:
model
- theSourceListModel
to use.
-
-
Method Detail
-
installSourceListControlBar
public void installSourceListControlBar(SourceListControlBar sourceListControlBar)
Installs the givenSourceListControlBar
at the base of thisSourceList
. This method can be called only once, and should generally be called during creation of theSourceList
.- Parameters:
sourceListControlBar
- theSourceListControlBar
to add.- Throws:
java.lang.IllegalStateException
- if aSourceListControlBar
has already been installed on thisSourceList
.java.lang.IllegalArgumentException
- if theSourceListControlBar
is null.
-
isSourceListControlBarInstalled
public boolean isSourceListControlBarInstalled()
True if there is aSourceListControlBar
installed on thisSourceList
.- Returns:
- true if there is a
SourceListControlBar
installed on thisSourceList
.
-
setSourceListContextMenuProvider
public void setSourceListContextMenuProvider(SourceListContextMenuProvider contextMenuProvider)
Sets theSourceListContextMenuProvider
to use for thisSourceList
.- Parameters:
contextMenuProvider
- theSourceListContextMenuProvider
to use for thisSourceList
.- Throws:
java.lang.IllegalArgumentException
- if theSourceListContextMenuProvider
is null.
-
dispose
public void dispose()
Uninstalls any listeners that thisSourceList
installed on creation, thereby allowing it to be garbage collected.
-
getSelectedItem
public SourceListItem getSelectedItem()
Gets the selectedSourceListItem
.- Returns:
- the selected
SourceListItem
.
-
setSelectedItem
public void setSelectedItem(SourceListItem item)
Selects the givenSourceListItem
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 thisSourceList
can have focus. When focusable and thisSourceList
has focus, the keyboard can be used for navigation.- Parameters:
focusable
- true if thisSourceList
should be focusable.
-
useIAppStyleScrollBars
public void useIAppStyleScrollBars()
Installs iApp style scroll bars on thisSourceList
.
-
getColorScheme
public SourceListColorScheme getColorScheme()
Gets theSourceListColorScheme
that thisSourceList
uses.- Returns:
- the
SourceListColorScheme
that thisSourceList
uses.
-
setColorScheme
public void setColorScheme(SourceListColorScheme colorScheme)
Sets theSourceListColorScheme
that thisSourceList
uses.- Parameters:
colorScheme
- theSourceListColorScheme
that thisSourceList
uses.
-
setTransferHandler
public void setTransferHandler(javax.swing.TransferHandler transferHandler)
Set's theTransferHandler
that thisSourceList
should use during drag and drop operations. If the given handler not null, then dragging will be turned on for theSourceList
. If the handler is null, then dragging will be turned off.- Parameters:
transferHandler
- theTransferHandler
for thisSourceList
. Can be null.
-
scrollItemToVisible
public void scrollItemToVisible(SourceListItem item)
Scrolls the givenSourceListItem
to be visible.- Parameters:
item
- theSourceListItem
to scroll to visible.
-
setExpanded
public void setExpanded(SourceListCategory category, boolean expanded)
Sets the expanded state of the givenSourceListCategory
.- 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 givenSourceListCategory
is not part of the associatedSourceListModel
.
-
setExpanded
public void setExpanded(SourceListItem item, boolean expanded)
Sets the expanded state of the givenSourceListItem
.- 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 givenSourceListItem
is not part of the associatedSourceListModel
.
-
getComponent
public javax.swing.JComponent getComponent()
Gets the user interface component representing thisSourceList
. The returnedJComponent
should be added to a container that will be displayed.- Returns:
- the user interface component representing this
SourceList
.
-
getModel
public SourceListModel getModel()
Gets theSourceListModel
backing thisSourceList
.- Returns:
- the
SourceListModel
backing thisSourceList
.
-
setToolTipProvider
public void setToolTipProvider(SourceListToolTipProvider toolTipProvider)
Sets theSourceListToolTipProvider
to use.- Parameters:
toolTipProvider
- the {@code SourceListToolTipProvider to use.
-
addSourceListClickListener
public void addSourceListClickListener(SourceListClickListener listener)
Adds theSourceListClickListener
to the list of listeners.- Parameters:
listener
- theSourceListClickListener
to add.
-
removeSourceListClickListener
public void removeSourceListClickListener(SourceListClickListener listener)
Removes theSourceListClickListener
to the list of listeners.- Parameters:
listener
- theSourceListClickListener
to remove.
-
addSourceListSelectionListener
public void addSourceListSelectionListener(SourceListSelectionListener listener)
Adds theSourceListSelectionListener
to the list of listeners.- Parameters:
listener
- theSourceListSelectionListener
to add.
-
removeSourceListSelectionListener
public void removeSourceListSelectionListener(SourceListSelectionListener listener)
Removes theSourceListSelectionListener
from the list of listeners.- Parameters:
listener
- theSourceListSelectionListener
to remove.
-
addSourceListExpansionListener
public void addSourceListExpansionListener(SourceListExpansionListener listener)
Adds theSourceListExpansionListener
to the list of listeners.- Parameters:
listener
- theSourceListExpansionListener
to add.
-
removeSourceListExpansionListener
public void removeSourceListExpansionListener(SourceListExpansionListener listener)
Removes theSourceListExpansionListener
from the list of listeners.- Parameters:
listener
- theSourceListExpansionListener
to remove.
-
-