danger.util
Interface ActiveFolder

All Superinterfaces:

ActiveList

All Known Implementing Classes:

StdActiveFolder

public interface ActiveFolder
extends ActiveList

Extension of ActiveList to add folder information. As with its superinterface, this interface provides methods for access, but not modification, of data.

The way that callbacks that get made on delegates bears a little extra description: If a change happens inside an open subfolder, then two callbacks get made: One is made for the item(s) affected in the folder (e.g., ActiveList.Delegate.onItemAdded(danger.util.ActiveList, java.lang.Object, int) or ActiveList.Delegate.onRangeRemoved(danger.util.ActiveList, java.lang.Object[], int)), and also a call to ActiveList.Delegate.onItemUpdated(danger.util.ActiveList, java.lang.Object, int) gets made for the folder itself. This allows for a folder's representation to be altered whenever its contents are altered. (For example, a folder might be rendered along with the number of items inside it.) If a change happens inside a closed subfolder, then no callback is propagated for the change in the folder, but a ActiveList.Delegate.onItemUpdated(danger.util.ActiveList, java.lang.Object, int) callback is still made for the folder itself.

Several of the methods in this class are prefixed with "tl". This stands for "top level," and such methods only operate on the top level of a folder, not descending into the folder's hierarchy, effectively treating subfolders the same as any other item.

Nested Class Summary

static interface	ActiveFolder.Delegate Interface for delegates that get notified on changes to instances of ActiveFolder.
static interface	ActiveFolder.FolderForEach Callback interface used for calls to folderForEach(danger.util.ActiveFolder.FolderForEach, boolean).
static class	ActiveFolder.WeakDelegateList List of delegates which are held onto weakly.

Nested classes/interfaces inherited from interface danger.util.ActiveList

ActiveList.ForEach

Method Summary

void	folderForEach(ActiveFolder.FolderForEach callback, boolean recurse) Call the given callback on each of the items in this folder, in order.
Object	getData() Get the arbitrary data object of the folder.
String	getTitle() Get the title of the folder.
boolean	isOpen() Get the open state of the folder.
void	setSynch(Object synch) Set the object to synchronize on.
int	tlEqIndexOf(Object item) Get the top-level index of the given item in the folder, compared with ==.
Object	tlGetItem(int which) Get the nth top-level item of this folder.
void	tlGetItems(int srcStart, int srcEnd, Object[] dest, int destStart) Get a range of top-level items, doing so atomically with respect to other operations on this instance.
int	tlSize() Return the top-level size of this folder.

Methods inherited from interface danger.util.ActiveList

addDelegate, eqIndexOf, forEach, getItem, getItems, removeDelegate, size

Method Detail

setSynch

void setSynch(Object synch)

Set the object to synchronize on. This will set the object for this instance, and it will also propagate it down to sub-folders. This is used so that a tree of folders can coordinate (e.g., a parent folder can synchronize and know that its children won't change in the middle of whatever it's doing). If passed as null, this means to make this instance synchronize on its own internal object and not to stop synchronizing.

Parameters:

synch - null-ok; the new synch object

isOpen

boolean isOpen()

Get the open state of the folder. This returns true when, and only when, an instance's contents should be displayed.

Returns:

the open state

getTitle

String getTitle()

Get the title of the folder.

Returns:

non-null; the title

getData

Object getData()

Get the arbitrary data object of the folder. This object may be used, for example, to hold UI-specific information such as what icon(s) to use to represent this instance.

Returns:

null-ok; the arbitrary data object

tlSize

int tlSize()

Return the top-level size of this folder. That is, return the number of items that live directly in this folder, not including the count of items in sub-folders.

Returns:

>= 0; the number of items

tlGetItem

Object tlGetItem(int which)

Get the nth top-level item of this folder. That is, this method does not consider elements inside subfolders.

Parameters:

which - >= 0 && < tlSize(); which item to get

Returns:

null-ok; the nth item

tlGetItems

void tlGetItems(int srcStart,
                int srcEnd,
                Object[] dest,
                int destStart)

Get a range of top-level items, doing so atomically with respect to other operations on this instance. Items inside subfolders are not considered (that is, folders are treated just like any other item directly in this instance).

Parameters:

srcStart - >= 0; the first item to get

srcEnd - >= srcBegin && <= tlSize(); the index just past the last item to get

dest - non-null; the destination buffer

destStart - >= 0 && <= (dest.length - (srcEnd - srcBegin)); where in dest to store the items

Throws:

NullPointerException - thrown if dest == null

IndexOutOfBoundsException - thrown if any of the indices is bad

folderForEach

void folderForEach(ActiveFolder.FolderForEach callback,
                   boolean recurse)

Call the given callback on each of the items in this folder, in order. All the callbacks happen as a single atomic operation with respect to other operations on this list. As such, if the callback misbehaves, it can wedge this instance for an indefinite period of time (e.g., deadlock). The recurse determines recursive behavior: If false, callbacks only get made for items directly in the folder (that is, a callback is made for subfolders but not for subfolders' contents); if true, callbacks get made for all items directly in the folder and in subfolders, using a preorder traversal, and ignoring the visibility of the items in terms of the folder's presentation as a list. (For a preorder traversal that respects visibility, use ActiveList.forEach(danger.util.ActiveList.ForEach).) Subfolders' items are traversed using recursive calls to this method (but on a different instance).

Parameters:

callback - non-null; the callback object

recurse - whether or not to recurse

tlEqIndexOf

int tlEqIndexOf(Object item)

Get the top-level index of the given item in the folder, compared with ==. (This method treats subfolders just as any other item directly in the folder.)

Parameters:

item - null-ok; the item to look for

Returns:

>= -1; the top-level index of the item or -1 if there is no such item directly in the folder