Package com.explodingpixels.macwidgets
Class SourceList
java.lang.Object
com.explodingpixels.macwidgets.SourceList
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
Here's how to create a simple
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
.
setSourceListContextMenuProvider(SourceListContextMenuProvider)
with an implementation
of SourceListContextMenuProvider
.-
Constructor Summary
ConstructorsConstructorDescriptionCreates aSourceList
with an emptySourceListModel
.SourceList
(SourceListModel model) Creates aSourceList
with the givenSourceListModel
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds theSourceListClickListener
to the list of listeners.void
Adds theSourceListExpansionListener
to the list of listeners.void
Adds theSourceListSelectionListener
to the list of listeners.void
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.Gets theSourceListColorScheme
that thisSourceList
uses.Gets the user interface component representing thisSourceList
.getModel()
Gets theSourceListModel
backing thisSourceList
.Gets the selectedSourceListItem
.void
installSourceListControlBar
(SourceListControlBar sourceListControlBar) Installs the givenSourceListControlBar
at the base of thisSourceList
.boolean
True if there is aSourceListControlBar
installed on thisSourceList
.void
Removes theSourceListClickListener
to the list of listeners.void
Removes theSourceListExpansionListener
from the list of listeners.void
Removes theSourceListSelectionListener
from the list of listeners.void
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
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
(TransferHandler transferHandler) Set's theTransferHandler
that thisSourceList
should use during drag and drop operations.void
Installs iApp style scroll bars on thisSourceList
.
-
Constructor Details
-
SourceList
public SourceList()Creates aSourceList
with an emptySourceListModel
. -
SourceList
Creates aSourceList
with the givenSourceListModel
.- Parameters:
model
- theSourceListModel
to use.
-
-
Method Details
-
installSourceListControlBar
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:
IllegalStateException
- if aSourceListControlBar
has already been installed on thisSourceList
.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
Sets theSourceListContextMenuProvider
to use for thisSourceList
.- Parameters:
contextMenuProvider
- theSourceListContextMenuProvider
to use for thisSourceList
.- Throws:
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
Gets the selectedSourceListItem
.- Returns:
- the selected
SourceListItem
.
-
setSelectedItem
Selects the givenSourceListItem
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 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
.- See Also:
-
getColorScheme
Gets theSourceListColorScheme
that thisSourceList
uses.- Returns:
- the
SourceListColorScheme
that thisSourceList
uses.
-
setColorScheme
Sets theSourceListColorScheme
that thisSourceList
uses.- Parameters:
colorScheme
- theSourceListColorScheme
that thisSourceList
uses.
-
setTransferHandler
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
Scrolls the givenSourceListItem
to be visible.- Parameters:
item
- theSourceListItem
to scroll to visible.
-
setExpanded
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:
IllegalArgumentException
- if the givenSourceListCategory
is not part of the associatedSourceListModel
.
-
setExpanded
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:
IllegalArgumentException
- if the givenSourceListItem
is not part of the associatedSourceListModel
.
-
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
Gets theSourceListModel
backing thisSourceList
.- Returns:
- the
SourceListModel
backing thisSourceList
.
-
setToolTipProvider
Sets theSourceListToolTipProvider
to use.- Parameters:
toolTipProvider
- theinvalid @code
{@code SourceListToolTipProvider to use.
-
addSourceListClickListener
Adds theSourceListClickListener
to the list of listeners.- Parameters:
listener
- theSourceListClickListener
to add.
-
removeSourceListClickListener
Removes theSourceListClickListener
to the list of listeners.- Parameters:
listener
- theSourceListClickListener
to remove.
-
addSourceListSelectionListener
Adds theSourceListSelectionListener
to the list of listeners.- Parameters:
listener
- theSourceListSelectionListener
to add.
-
removeSourceListSelectionListener
Removes theSourceListSelectionListener
from the list of listeners.- Parameters:
listener
- theSourceListSelectionListener
to remove.
-
addSourceListExpansionListener
Adds theSourceListExpansionListener
to the list of listeners.- Parameters:
listener
- theSourceListExpansionListener
to add.
-
removeSourceListExpansionListener
Removes theSourceListExpansionListener
from the list of listeners.- Parameters:
listener
- theSourceListExpansionListener
to remove.
-