org.openide.nodes

Class Children.Keys<T>

java.lang.Object

org.openide.nodes.Children

org.openide.nodes.Children.Array

org.openide.nodes.Children.Keys<T>

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

BeanChildren, FilterNode.Children, Index.KeysChildren

Enclosing class:

Children

public abstract static class Children.Keys<T>
extends Children.Array

Implements an array of child nodes associated nonuniquely with keys and sorted by these keys. There is a method that should for each key create an array of nodes that represents the key.

This class is preferable to Children.Array because

1. It more clearly separates model from view and encourages use of a discrete model.
2. It correctly handles adding, removing, and reordering children while preserving existing node selections in a tree (or other) view where possible.

Typical usage:

1. Subclass.
2. Decide what type your key should be.
3. Implement Children.Keys.createNodes(T) to create some nodes (usually exactly one) per key.
4. Override Children.addNotify() to compute a set of keys and set it using Children.Keys.setKeys(Collection). The collection may be ordered.
5. Override Children.removeNotify() to just call setKeys on Collections.EMPTY_SET.
6. When your model changes, call setKeys with the new set of keys. Children.Keys will be smart and calculate exactly what it needs to do effficiently.
7. (Optional) if your notion of what the node for a given key changes (but the key stays the same), you can call Children.Keys.refreshKey(T). Usually this is not necessary.

Note that for simple cases, it may be preferable to subclass ChildFactory and pass the result to create(); doing so makes it easy to switch to using child nodes computed on a background thread if necessary for performance reasons.

Related documentation

• NetBeans System Properties Module Tutorial

Nested Class Summary

Nested classes/interfaces inherited from class org.openide.nodes.Children

Children.Array, Children.Keys<T>, Children.Map<T>, Children.SortedArray, Children.SortedMap<T>

Field Summary

Fields inherited from class org.openide.nodes.Children.Array

nodes

Fields inherited from class org.openide.nodes.Children

LEAF, MUTEX

Constructor Summary

Constructors

Modifier	Constructor and Description
	Keys()
protected	Keys(boolean lazy) Constructor for optional "lazy behavoir" (tries to avoid computation of nodes if possible).

Method Summary

Modifier and Type	Method and Description
boolean	add(Node[] arr) Deprecated. Do not use! Just call Children.Keys.setKeys(Collection) with a larger set.
Object	clone() Special handling for clonning.
protected abstract Node[]	createNodes(T key) Create nodes for a given key.
protected void	destroyNodes(Node[] arr) Called when the nodes have been removed from the children.
protected void	refreshKey(T key) Refresh the child nodes for a given key.
boolean	remove(Node[] arr) Deprecated. Do not use! Just call Children.Keys.setKeys(Collection) with a smaller set.
protected void	setBefore(boolean b) Set whether new nodes should be added to the beginning or end of sublists for a given key.
protected void	setKeys(Collection<? extends T> keysSet) Set new keys for this children object.
protected void	setKeys(T[] keys) Set keys for this list.

Methods inherited from class org.openide.nodes.Children.Array

initCollection, refresh

Methods inherited from class org.openide.nodes.Children

addNotify, create, createLazy, findChild, getNode, getNodeAt, getNodes, getNodes, getNodesCount, getNodesCount, isInitialized, nodes, removeNotify, snapshot

Methods inherited from class java.lang.Object

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

Constructor Detail

Keys

public Keys()

Keys

protected Keys(boolean lazy)

Constructor for optional "lazy behavoir" (tries to avoid computation of nodes if possible).

There are certain requirements for usage of lazy mode: It is forbidden to create more than 1 node in Children.Keys.createNodes(T) for key. In optimal case there should be 1:1 pairing between key and Node, but it is also possible to have 1:0 pairing - create no node (return null). In such case after detection that there is no Node for key, the key is automatically removed and change (removal of "dummy" Node) is fired.

Parameters:

lazy - whether to introduce lazy behavior

Since:

org.openide.nodes 7.6

Method Detail

clone

public Object clone()

Special handling for clonning.

Overrides:

clone in class Children.Array

Returns:

the cloned array for this children

add

@Deprecated
public boolean add(Node[] arr)

Deprecated. Do not use! Just call Children.Keys.setKeys(Collection) with a larger set.

Description copied from class: Children

Add nodes to this container but do not call this method. If you think you need to do this probably you really wanted to use Children.Keys.setKeys(java.util.Collection<? extends T>) instead. The parent node of these nodes is changed to the parent node of this list. Each node can be added only once. If there is some reason a node cannot be added, for example if the node expects only a special type of subnodes, the method should do nothing and return false to signal that the addition has not been successful.

This method should be implemented by subclasses to filter some nodes, etc.

Overrides:

add in class Children.Array

Parameters:

arr - set of nodes to add to the list

Returns:

true if successfully added

remove

@Deprecated
public boolean remove(Node[] arr)

Deprecated. Do not use! Just call Children.Keys.setKeys(Collection) with a smaller set.

Description copied from class: Children

Remove nodes from the list. Only nodes that are present are removed.

Overrides:

remove in class Children.Array

Parameters:

arr - nodes to be removed

Returns:

true if the nodes could be removed

refreshKey

protected final void refreshKey(T key)

Refresh the child nodes for a given key.

Parameters:

key - the key to refresh

setKeys

protected final void setKeys(Collection<? extends T> keysSet)

Set new keys for this children object. Setting of keys does not necessarily lead to the creation of nodes. It happens only when the list has already been initialized.

Parameters:

keysSet - the keys for the nodes (collection of any objects)

setKeys

protected final void setKeys(T[] keys)

Set keys for this list.

Parameters:

keys - the keys for the nodes

See Also:

Children.Keys.setKeys(Collection)

setBefore

protected final void setBefore(boolean b)

Set whether new nodes should be added to the beginning or end of sublists for a given key. Generally should not be used.

Parameters:

b - true if the children should be added before

createNodes

protected abstract Node[] createNodes(T key)

Create nodes for a given key.

Parameters:

key - the key

Returns:

child nodes for this key or null if there should be no nodes for this key

destroyNodes

protected void destroyNodes(Node[] arr)

Called when the nodes have been removed from the children. This method should allow subclasses to clean the nodes somehow.

Current implementation notifies all listeners on the nodes that nodes have been deleted.

Parameters:

arr - array of deleted nodes