edu.rice.cs.util.docnavigation
Class JListNavigator<ItemT extends INavigatorItem>

java.lang.Object
  
      edu.rice.cs.util.docnavigation.JListNavigator<ItemT>

All Implemented Interfaces:

IAWTContainerNavigatorActor, IDocumentNavigator<ItemT>

Direct Known Subclasses:

JListSortNavigator

 class JListNavigator<ItemT extends INavigatorItem>
extends 
implements IDocumentNavigator<ItemT>

This class is an extension of JList that adds data shadowing the model embedded in a JList. Since all changes to the model (except for the selected item!) must go through this interface, we can support access to methods from non-event threads as long as these methods do not modify the model. However, all of the public methods that access and modify the model (the latter only running in the event thread) must be atomic relative to each other, so synchronization is required in most cases. TODO: generify this class and IDocumentNavigator with respect to its element type once JList is.

Nested Class Summary

private static class

JListNavigator.CustomListCellRenderer The cell renderer for this list.

Field Summary

private ItemT	_current The current selection value.
protected	_model The list model (extending AbstractListModel) for this JList.
private JListNavigator.CustomListCellRenderer	_renderer The cell renderer for this JList
private ArrayList<INavigationListener<? super ItemT>>	navListeners the collection of INavigationListeners listening to this JListNavigator

Fields inherited from interface edu.rice.cs.util.docnavigation.IDocumentNavigator

MODEL_INITIATED_PROPERTY_NAME

Constructor Summary

JListNavigator()
Standard constructor.

Method Summary

void	addDocument(ItemT doc) Adds the document doc to this navigator.
void	addDocument(ItemT doc, String path) Adds the document to this navigator and ignores the specified path.
void	addNavigationListener(INavigationListener<? super ItemT> listener) Adds listener to the collection of listeners.
void	addTopLevelGroup(String name, INavigatorItemFilter<? super ItemT> f)
Container	asContainer() Returns a Container representation of this navigator
void	clear() Clears the navigator and removes all documents.
boolean	contains(ItemT doc) Returns whether or not the navigator contains the document
<InType,ReturnType> ReturnType	execute(IDocumentNavigatorAlgo<ItemT,InType,ReturnType> algo, InType input) Executes the list case of the visitor.
ItemT	getCurrent() Returns the currently selected item, or null if none.
int	getDocumentCount() Returns the number of INavigatorItems contained by this IDocumentNavigator
ArrayList<ItemT>	getDocuments() Returns all the IDocuments in the collection in enumeration order.
int	getDocumentSelectedCount()
ArrayList<ItemT>	getDocumentsInBin(String binName) Returns all the IDocuments contained in the specified bin.
ItemT	getFirst() Gets the first document in the series.
protected ItemT	getFromModel(int i) A typesafe version of _model.get(i).
int	getGroupSelectedCount()
ItemT	getLast() Gets the first document in the series.
Object	getModelLock() Returns the model lock.
Set<String>	getNamesOfSelectedTopLevelGroup() Returns the names of the top level groups that the selected items descend from.
Collection<INavigationListener<? super ItemT>>	getNavigatorListeners() Returns a collection of all listeners registered with this navigator.
ItemT	getNext(ItemT doc) Gets the next document after doc in the series.
ItemT	getPrevious(ItemT doc) Gets the previous document in the series.
Component	getRenderer()
List<ItemT>	getSelectedDocuments()
List<File>	getSelectedFolders()
int	getSelectionCount()
private void	init( m)
boolean	isDocumentSelected()
boolean	isEmpty() Returns whether this IDocumentNavigator contains any INavigatorItems.
boolean	isGroupSelected()
boolean	isNextChangeModelInitiated()
boolean	isRootSelected() Returns true if the root is selected.
boolean	isSelectedAt(int x, int y) Returns true if the item at the x,y coordinate of the navigator pane is currently selected.
boolean	isSelectedInGroup(ItemT i)
boolean	isTopLevelGroupSelected() Returns true if at least one top level group is selected, false otherwise.
void	refreshDocument(ItemT doc, String path) Resets a given INavigatorItem in the tree.
ItemT	removeDocument(ItemT doc) Removes the document from the navigator.
void	removeNavigationListener(INavigationListener<? super ItemT> listener) Unregisters the listener listener
void	requestSelectionUpdate(ItemT doc) Since in the JListNavigator it is impossible to select anything but an INavigatorItem, this method doesn't need to do anything.
void	selectDocument(ItemT doc) Sets the specified document as selected in the navigator.
boolean	selectDocumentAt(int x, int y) Selects the document at the x,y coordinate of the navigator pane and sets it to be the currently active document.
void	setNextChangeModelInitiated(boolean b) Marks the next selection change as model-initiated (true) or user-initiated (false; default).
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface edu.rice.cs.util.docnavigation.IDocumentNavigator

addDocument, addDocument, addFocusListener, addNavigationListener, addTopLevelGroup, contains, execute, getFocusListeners, getNext, getPrevious, isSelectedInGroup, refreshDocument, removeDocument, removeFocusListener, removeNavigationListener, repaint, requestSelectionUpdate, selectDocument

Field Detail

_model

protected volatile  _model

The list model (extending AbstractListModel) for this JList.

_current

private volatile ItemT extends INavigatorItem _current

The current selection value. A cached copy of getSelectedValue().

_renderer

private volatile JListNavigator.CustomListCellRenderer _renderer

The cell renderer for this JList

navListeners

private final ArrayList<INavigationListener<? super ItemT extends INavigatorItem>> navListeners

the collection of INavigationListeners listening to this JListNavigator

Constructor Detail

JListNavigator

public JListNavigator()

Standard constructor.

Method Detail

init

private void init( m)

addDocument

public void addDocument(ItemT doc)

Adds the document doc to this navigator. Should only be executed in event thread.

Parameters:

doc - the document to add

addDocument

public void addDocument(ItemT doc,
                        String path)

Adds the document to this navigator and ignores the specified path. Should only be executed in event thread.

Parameters:

doc - the document to add -- assumed to be of type T

path - unused parameter in this class

getFromModel

protected ItemT getFromModel(int i)

A typesafe version of _model.get(i). This is a workaround for the non-generic implementation of DefaultListModel, and should be removed once that is fixed.

getNext

public ItemT getNext(ItemT doc)

Gets the next document after doc in the series.

Parameters:

doc - the document to reference from

Returns:

the document after doc in the list; if doc is the last document, returns doc

getPrevious

public ItemT getPrevious(ItemT doc)

Gets the previous document in the series.

Parameters:

doc - to reference from

Returns:

the document which comes before doc in the list

getFirst

public ItemT getFirst()

Gets the first document in the series.

Specified by:

getFirst in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the first document in the collection

getLast

public ItemT getLast()

Gets the first document in the series.

Specified by:

getLast in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the first document in the collection

getCurrent

public ItemT getCurrent()

Returns the currently selected item, or null if none.

Specified by:

getCurrent in interface IDocumentNavigator<ItemT extends INavigatorItem>

getModelLock

public Object getModelLock()

Returns the model lock.

Specified by:

getModelLock in interface IDocumentNavigator<ItemT extends INavigatorItem>

removeDocument

public ItemT removeDocument(ItemT doc)

Removes the document from the navigator. Should only be executed in event thread.

Parameters:

doc - the document to remove

refreshDocument

public void refreshDocument(ItemT doc,
                            String path)

Resets a given INavigatorItem in the tree. This may affect the placement of the item or its display to reflect any changes made in the model. Should only be executed in event thread.

Parameters:

doc - the docment to be refreshed

Throws:

IllegalArgumentException - if this navigator contains no document that is equal to the passed document.

selectDocument

public void selectDocument(ItemT doc)

Sets the specified document as selected in the navigator. Only executes in event thread.

Parameters:

doc - the document to select

contains

public boolean contains(ItemT doc)

Returns whether or not the navigator contains the document

Parameters:

doc - the document to find

Returns:

true if this list contains doc (using identity as equality measure), false if not.

getDocuments

public ArrayList<ItemT> getDocuments()

Description copied from interface: IDocumentNavigator

Returns all the IDocuments in the collection in enumeration order.

Specified by:

getDocuments in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

an Enumeration of the documents in this list (ordering is consistent with getNext() and getPrev()). This cast in this method required to work around the stupid partial generification of DefaultListModel in Java 1.5. The class should be generic: DefaultListModel { ... Enumeration elements() {...} ... } instead of DefaultListModel { ... Enumeration elements() {...} ... }.

getDocumentsInBin

public ArrayList<ItemT> getDocumentsInBin(String binName)

Returns all the IDocuments contained in the specified bin. Always empty.

Specified by:

getDocumentsInBin in interface IDocumentNavigator<ItemT extends INavigatorItem>

Parameters:

binName - name of bin

Returns:

an INavigatorItem enumeration of this navigator's contents.

getDocumentCount

public int getDocumentCount()

Description copied from interface: IDocumentNavigator

Returns the number of INavigatorItems contained by this IDocumentNavigator

Specified by:

getDocumentCount in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the number of documents in the navigator.

isEmpty

public boolean isEmpty()

Description copied from interface: IDocumentNavigator

Returns whether this IDocumentNavigator contains any INavigatorItems.

Specified by:

isEmpty in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

whether or not the navigator is empty.

addNavigationListener

public void addNavigationListener(INavigationListener<? super ItemT> listener)

Adds listener to the collection of listeners.

Parameters:

listener -

removeNavigationListener

public void removeNavigationListener(INavigationListener<? super ItemT> listener)

Unregisters the listener listener

Parameters:

listener -

getNavigatorListeners

public Collection<INavigationListener<? super ItemT>> getNavigatorListeners()

Description copied from interface: IDocumentNavigator

Returns a collection of all listeners registered with this navigator.

Specified by:

getNavigatorListeners in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the navigator listeners.

clear

public void clear()

Clears the navigator and removes all documents. Should only be executed from event thread.

Specified by:

clear in interface IDocumentNavigator<ItemT extends INavigatorItem>

execute

public <InType,ReturnType> ReturnType execute(IDocumentNavigatorAlgo<ItemT,InType,ReturnType> algo,
                                              InType input)

Executes the list case of the visitor.

Parameters:

algo - the visitor to execute

input - the input to run on the visitor

asContainer

public Container asContainer()

Returns a Container representation of this navigator

Specified by:

asContainer in interface IAWTContainerNavigatorActor

Specified by:

asContainer in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

an AWT component which interacts with this document navigator

selectDocumentAt

public boolean selectDocumentAt(int x,
                                int y)

Selects the document at the x,y coordinate of the navigator pane and sets it to be the currently active document. Should only be called from event-handling thread.

Specified by:

selectDocumentAt in interface IDocumentNavigator<ItemT extends INavigatorItem>

Parameters:

x - the x coordinate of the navigator pane

y - the y coordinate of the navigator pane

isSelectedAt

public boolean isSelectedAt(int x,
                            int y)

Returns true if the item at the x,y coordinate of the navigator pane is currently selected. Always false for JListSortNavigator Only runs in event thread.

Specified by:

isSelectedAt in interface IDocumentNavigator<ItemT extends INavigatorItem>

Parameters:

x - the x coordinate of the navigator pane

y - the y coordinate of the navigator pane

Returns:

true if the item is currently selected

getRenderer

public Component getRenderer()

Specified by:

getRenderer in interface IAWTContainerNavigatorActor

Returns:

the renderer for this object.

getSelectionCount

public int getSelectionCount()

Specified by:

getSelectionCount in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the number of selected items. Always 1 for JListNavigator

isGroupSelected

public boolean isGroupSelected()

Specified by:

isGroupSelected in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

true if at least one group of INavigatorItems is selected; always false for JListNavigator

getGroupSelectedCount

public int getGroupSelectedCount()

Specified by:

getGroupSelectedCount in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the number of groups selected. Always 0 for JListSortNavigator

getSelectedFolders

public List<File> getSelectedFolders()

Specified by:

getSelectedFolders in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the folders currently selected. Always empty for JListSortNavigator

isDocumentSelected

public boolean isDocumentSelected()

Specified by:

isDocumentSelected in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

true if at least one document is selected; always true for JListNavigator

getDocumentSelectedCount

public int getDocumentSelectedCount()

Specified by:

getDocumentSelectedCount in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the number of documents selected. Same as getSelectionCount for JListSortNavigator.

getSelectedDocuments

public List<ItemT> getSelectedDocuments()

Specified by:

getSelectedDocuments in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

the documents currently selected. Only runs in event thread.

isRootSelected

public boolean isRootSelected()

Returns true if the root is selected. Only runs in event thread.

Specified by:

isRootSelected in interface IDocumentNavigator<ItemT extends INavigatorItem>

isSelectedInGroup

public boolean isSelectedInGroup(ItemT i)

Returns:

true if the INavigatorItem is in the selected group, if a group is selected.

addTopLevelGroup

public void addTopLevelGroup(String name,
                             INavigatorItemFilter<? super ItemT> f)

isTopLevelGroupSelected

public boolean isTopLevelGroupSelected()

Description copied from interface: IDocumentNavigator

Returns true if at least one top level group is selected, false otherwise.

Specified by:

isTopLevelGroupSelected in interface IDocumentNavigator<ItemT extends INavigatorItem>

getNamesOfSelectedTopLevelGroup

public Set<String> getNamesOfSelectedTopLevelGroup()
                                            throws GroupNotSelectedException

Returns the names of the top level groups that the selected items descend from. Always throws a GroupNotSelectedException for JListSortNavigator

Specified by:

getNamesOfSelectedTopLevelGroup in interface IDocumentNavigator<ItemT extends INavigatorItem>

Throws:

GroupNotSelectedException

requestSelectionUpdate

public void requestSelectionUpdate(ItemT doc)

Since in the JListNavigator it is impossible to select anything but an INavigatorItem, this method doesn't need to do anything. See JTreeSortNavigator and IDocumentNavigator.

toString

public String toString()

setNextChangeModelInitiated

public void setNextChangeModelInitiated(boolean b)

Marks the next selection change as model-initiated (true) or user-initiated (false; default).

Specified by:

setNextChangeModelInitiated in interface IDocumentNavigator<ItemT extends INavigatorItem>

isNextChangeModelInitiated

public boolean isNextChangeModelInitiated()

Specified by:

isNextChangeModelInitiated in interface IDocumentNavigator<ItemT extends INavigatorItem>

Returns:

whether the next selection change is model-initiated (true) or user-initiated (false).