org.openide.nodes
Class Node

java.lang.Object
  |
  +--java.beans.FeatureDescriptor
        |
        +--org.openide.nodes.Node

Direct Known Subclasses:

AbstractNode, FilterNode

public abstract class Node

extends FeatureDescriptor

A node represents one element in a hierarchy of objects (beans). It provides all methods that are needed for communication between the IDE and the bean.

The node has three purposes:

1. visually represent the object in the tree hierarchy (i.e. Explorer)
2. provide sets of properties for that object (i.e. Component Inspector, Property Sheet)
3. offer actions to perform on itself

Frequently nodes are created to represent data objects. But they may also represent anything to be displayed to the user or manipulated programmatically, even if they have no data directly stored behind them; for example, a control panel or debugger breakpoint.

There are two listeners in this class: PropertyChangeListener and NodeListener (which extends PropertyChangeListener). The first is designed to listen on properties that can be returned from getPropertySets(), the later for listening on changes in the node itself (including the name, children, parent, set of properties, icons, etc.). Be sure to distinguish between these two.

The node is cloneable. When a node is cloned, it is initialized with an empty set of listeners and no parent. The display name and short description are copied to the new node. The set of properties is shared.

Inner Class Summary

static interface	Node.Cookie Marker interface for all cookies.
static interface	Node.Handle Serializable node reference.
static class	Node.IndexedProperty Description of an indexed property and operations on it.
static class	Node.Property Description of a Bean property on a node, and operations on it.
static class	Node.PropertySet Class that represents one set of properties.

Field Summary

static Node	EMPTY An empty leaf node.
static String	PROP_COOKIE Property for a node's cookie set.
static String	PROP_DISPLAY_NAME Property for node display name.
static String	PROP_ICON Property for the normal (closed) icon of a node.
static String	PROP_NAME Property for internal (not displayable) name of a node.
static String	PROP_OPENED_ICON Property for the opened icon of a node.
static String	PROP_PARENT_NODE Property for a node's parent.
static String	PROP_PROPERTY_SETS Property for a node's list of property sets.
static String	PROP_SHORT_DESCRIPTION Property for short description of a node.

Constructor Summary

protected

Node(Children h) Creates a new node with a given hierarchy of children.

Method Summary

void	addNodeListener(NodeListener l) Add a listener to changes in the node's intrinsic properties (name, cookies, etc.).
void	addPropertyChangeListener(PropertyChangeListener l) Add a listener to the node's computed Bean properties.
abstract boolean	canCopy() Test whether this node permits copying.
abstract boolean	canCut() Test whether this node permits cutting.
abstract boolean	canDestroy() Test whether this node can be deleted.
abstract boolean	canRename() Test whether this node can be renamed.
abstract Transferable	clipboardCopy() Called when a node is to be copied to the clipboard.
abstract Transferable	clipboardCut() Called when a node is to be cut to the clipboard.
protected Object	clone() Implements Object.clone() to behave correctly if cloning is desired.
abstract Node	cloneNode() Clone the node.
void	destroy() Remove the node from its parent and deletes it.
abstract Transferable	drag() Called when a drag is started with this node.
protected void	fireCookieChange() Fires a change event for PROP_COOKIE.
protected void	fireDisplayNameChange(String o, String n) Allow subclasses that override the getDisplayName method to fire the changes of the name by itself.
protected void	fireIconChange() Fire a change event for PROP_ICON.
protected void	fireNameChange(String o, String n) Allow subclasses that override the getName method to fire the changes of the name by itself.
protected void	fireNodeDestroyed() To all node listeners fire node destroyed notification.
protected void	fireOpenedIconChange() Fire a change event for PROP_OPENED_ICON.
protected void	firePropertyChange(String name, Object o, Object n) Fire a property change event.
protected void	firePropertySetsChange(Node.PropertySet[] o, Node.PropertySet[] n) Fires a (Bean) property change event (for PROP_PROPERTY_SETS).
protected void	fireShortDescriptionChange(String o, String n) Allow subclasses that override the getShortDescription method to fire the changes of the description by itself.
SystemAction[]	getActions() Get the set of actions associated with this node.
Children	getChildren() Get the list of children.
SystemAction[]	getContextActions() Get a special set of actions for situations when this node is displayed as a context.
JPopupMenu	getContextMenu() Make a context menu for this node.
abstract Node.Cookie	getCookie(Class type) Get a cookie for this node.
abstract Component	getCustomizer() Get the customizer component.
abstract SystemAction	getDefaultAction() Get the default action for this node.
abstract PasteType	getDropType(Transferable t, int action, int index) Determine if there is a paste operation that can be performed on provided transferable.
abstract Node.Handle	getHandle() Obtain handle for this node (for serialization).
abstract HelpCtx	getHelpCtx() Get context help associated with this node.
abstract Image	getIcon(int type) Find an icon for this node (in the closed state).
abstract NewType[]	getNewTypes() Get the new types that can be created in this node.
abstract Image	getOpenedIcon(int type) Find an icon for this node (in the open state).
Node	getParentNode() Get the parent node.
abstract PasteType[]	getPasteTypes(Transferable t) Determine which paste operations are allowed when a given transferable is in the clipboard.
abstract Node.PropertySet[]	getPropertySets() Get the list of property sets for this node.
abstract boolean	hasCustomizer() Test whether there is a customizer for this node.
protected boolean	hasPropertyChangeListener() Allows to figure out, whether the node has any PropertyChangeListeners attached.
boolean	isLeaf() Test whether the node is a leaf, or may contain children.
void	removeNodeListener(NodeListener l) Remove a node listener.
void	removePropertyChangeListener(PropertyChangeListener l) Remove a Bean property change listener.
void	setDisplayName(String s) Set the display name.
void	setName(String s) Set the system name.
void	setShortDescription(String s) Set the short description of the node.
String	toString()

Methods inherited from class java.beans.FeatureDescriptor

attributeNames, getDisplayName, getName, getShortDescription, getValue, isExpert, isHidden, isPreferred, setExpert, setHidden, setPreferred, setValue

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY

public static final Node EMPTY

An empty leaf node.

PROP_DISPLAY_NAME

public static final String PROP_DISPLAY_NAME

Property for node display name.

PROP_NAME

public static final String PROP_NAME

Property for internal (not displayable) name of a node. This name is often used to look up a node in the hierarchy, so it should be chosen to be simple.

PROP_SHORT_DESCRIPTION

public static final String PROP_SHORT_DESCRIPTION

Property for short description of a node.

PROP_ICON

public static final String PROP_ICON

Property for the normal (closed) icon of a node.

PROP_OPENED_ICON

public static final String PROP_OPENED_ICON

Property for the opened icon of a node.

PROP_PARENT_NODE

public static final String PROP_PARENT_NODE

Property for a node's parent.

PROP_PROPERTY_SETS

public static final String PROP_PROPERTY_SETS

Property for a node's list of property sets.

PROP_COOKIE

public static final String PROP_COOKIE

Property for a node's cookie set.

Constructor Detail

Node

protected Node(Children h)
        throws IllegalStateException

Creates a new node with a given hierarchy of children.

Throws:

IllegalStateException - if the hierarchy is already in use by a different node

Method Detail

clone

protected Object clone()
                throws CloneNotSupportedException

Implements Object.clone() to behave correctly if cloning is desired. But Cloneable is not declared by default.

The default implementation checks whether the child list implements Cloneable, and if so, it clones the children. If the child list does not support cloning, Children.LEAF is used instead for the children. The parent of this node is set to null and an empty set of listeners is attached to the node.

Overrides:

clone in class Object

Returns:

the cloned version of the node

Throws:

CloneNotSupportedException - if the children cannot be cloned in spite of implementing Cloneable

cloneNode

public abstract Node cloneNode()

Clone the node. The newly created node should reference the same object is this node does, but it should not be inserted as a child to any other node. Also it should have an empty set of listeners. In all other respects the node should behave exactly as the original one does.

Returns:

copy of this node

setName

public void setName(String s)

Set the system name. Fires a property change event.

Overrides:

setName in class FeatureDescriptor

Parameters:

s - the new name

Throws:

IllegalArgumentException - if the new name cannot represent a valid node name

setDisplayName

public void setDisplayName(String s)

Set the display name. Fires a property change event.

Overrides:

setDisplayName in class FeatureDescriptor

Parameters:

s - the new name

setShortDescription

public void setShortDescription(String s)

Set the short description of the node. Fires a property change event.

This description may be used for tool tips, etc.

Overrides:

setShortDescription in class FeatureDescriptor

Parameters:

s - the new description

getIcon

public abstract Image getIcon(int type)

Find an icon for this node (in the closed state).

Parameters:

type - constant from BeanInfo

Returns:

icon to use to represent the node

getOpenedIcon

public abstract Image getOpenedIcon(int type)

Find an icon for this node (in the open state). This icon is used when the node may have children and is expanded.

Parameters:

type - constant from BeanInfo

Returns:

icon to use to represent the node when open

getHelpCtx

public abstract HelpCtx getHelpCtx()

Get context help associated with this node.

Returns:

the context help object (could be null or HelpCtx.DEFAULT_HELP)

getChildren

public final Children getChildren()

Get the list of children.

Returns:

the children

isLeaf

public final boolean isLeaf()

Test whether the node is a leaf, or may contain children.

Returns:

true if the children list is actually Children.LEAF

getParentNode

public final Node getParentNode()

Get the parent node.

Returns:

the parent node, or null if this node is the root of a hierarchy

canRename

public abstract boolean canRename()

Test whether this node can be renamed. If true, one can use FeatureDescriptor.getName() to obtain the current name and setName(java.lang.String) to change it.

Returns:

true if the node can be renamed

canDestroy

public abstract boolean canDestroy()

Test whether this node can be deleted.

Returns:

true if can

destroy

public void destroy()
             throws IOException

Remove the node from its parent and deletes it. The default implementation obtains write access to the children's lock, and removes the node from its parent (if any). Also fires a property change.

This may be overridden by subclasses to do any additional cleanup.

Throws:

IOException - if something fails

getPropertySets

public abstract Node.PropertySet[] getPropertySets()

Get the list of property sets for this node. E.g. typically there may be one for normal Bean properties, one for expert properties, and one for hidden properties.

Returns:

the property sets

clipboardCopy

public abstract Transferable clipboardCopy()
                                    throws IOException

Called when a node is to be copied to the clipboard.

Returns:

the transferable object representing the content of the clipboard

Throws:

IOException - when the copy cannot be performed

clipboardCut

public abstract Transferable clipboardCut()
                                   throws IOException

Called when a node is to be cut to the clipboard.

Returns:

the transferable object representing the content of the clipboard

Throws:

IOException - when the cut cannot be performed

drag

public abstract Transferable drag()
                           throws IOException

Called when a drag is started with this node. The node can attach a transfer listener to ExTransferable and will be then notified about progress of the drag (accept/reject).

Returns:

transferable to represent this node during a drag

Throws:

IOException - if a drag cannot be started

canCopy

public abstract boolean canCopy()

Test whether this node permits copying.

Returns:

true if so

canCut

public abstract boolean canCut()

Test whether this node permits cutting.

Returns:

true if so

getPasteTypes

public abstract PasteType[] getPasteTypes(Transferable t)

Determine which paste operations are allowed when a given transferable is in the clipboard. For example, a node representing a Java package will permit classes to be pasted into it.

Parameters:

t - the transferable in the clipboard

Returns:

array of operations that are allowed

getDropType

public abstract PasteType getDropType(Transferable t,
                                      int action,
                                      int index)

Determine if there is a paste operation that can be performed on provided transferable. Used by drag'n'drop code to check whether the drop is possible.

Parameters:

t - the transferable

action - the drag'n'drop action to do DnDConstants.ACTION_MOVE, ACTION_COPY, ACTION_LINK

index - index between children the drop occured at or -1 if not specified

Returns:

null if the transferable cannot be accepted or the paste type to execute when the drop occures

getNewTypes

public abstract NewType[] getNewTypes()

Get the new types that can be created in this node. For example, a node representing a Java package will permit classes to be added.

Returns:

array of new type operations that are allowed

getActions

public SystemAction[] getActions()

Get the set of actions associated with this node. This may be used e.g. in constructing a context menu.

By default returns the actions in NodeOp.getDefaultActions().

Returns:

system actions appropriate to the node

getContextActions

public SystemAction[] getContextActions()

Get a special set of actions for situations when this node is displayed as a context.

For example, right-clicking on a parent node in a hierarchical view (such as the normal Explorer) should use getActions. However, if this node is serving as the parent of a (say) a window tab full of icons (e.g., in IconView), and the users right-clicks on the empty space in this pane, then this method should be used to get the appropriate actions for a popup menu.

Note that in the Windows UI system, e.g., these action sets are quite different.

Returns:

actions for a context. In the default implementation, same as getActions().

getDefaultAction

public abstract SystemAction getDefaultAction()

Get the default action for this node. This action can but need not be one from the list returned from getActions(). If so, the popup menu returned from getContextMenu() is encouraged to highlight the action.

Returns:

default action, or null if there should be none

getContextMenu

public final JPopupMenu getContextMenu()

Make a context menu for this node. The menu is constructed from the set of actions returned by getActions().

Returns:

the popup menu

hasCustomizer

public abstract boolean hasCustomizer()

Test whether there is a customizer for this node. If true, the customizer can be obtained via getCustomizer().

Returns:

true if there is a customizer

getCustomizer

public abstract Component getCustomizer()

Get the customizer component.

Returns:

the component, or null if there is no customizer

getCookie

public abstract Node.Cookie getCookie(Class type)

Get a cookie for this node.

The set of cookies can change. If a node changes its set of cookies, it fires a property change event with PROP_COOKIE.

Parameters:

type - the representation class of the cookie

Returns:

a cookie assignable to that class, or null if this node has no such cookie

getHandle

public abstract Node.Handle getHandle()

Obtain handle for this node (for serialization). The handle can be serialized and Node.Handle.getNode() used after deserialization to obtain the original node.

Returns:

the handle, or null if this node is not persistable

addNodeListener

public final void addNodeListener(NodeListener l)

Add a listener to changes in the node's intrinsic properties (name, cookies, etc.).

Parameters:

l - the listener to add

removeNodeListener

public final void removeNodeListener(NodeListener l)

Remove a node listener.

Parameters:

l - the listener

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener l)

Add a listener to the node's computed Bean properties.

Parameters:

l - the listener

hasPropertyChangeListener

protected final boolean hasPropertyChangeListener()

Allows to figure out, whether the node has any PropertyChangeListeners attached.

Returns:

True if node has one or more PropertyChangeListeners attached.

Since:

1.36

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener l)

Remove a Bean property change listener.

Parameters:

l - the listener

firePropertyChange

protected final void firePropertyChange(String name,
                                        Object o,
                                        Object n)

Fire a property change event.

Parameters:

name - name of changed property (from getPropertySets())

o - old value

n - new value

fireNameChange

protected final void fireNameChange(String o,
                                    String n)

Allow subclasses that override the getName method to fire the changes of the name by itself. Please notice that default implementation of setName will fire the change by itself.

fireDisplayNameChange

protected final void fireDisplayNameChange(String o,
                                           String n)

Allow subclasses that override the getDisplayName method to fire the changes of the name by itself. Please notice that default implementation of setDisplayName will fire the change by itself.

fireShortDescriptionChange

protected final void fireShortDescriptionChange(String o,
                                                String n)

Allow subclasses that override the getShortDescription method to fire the changes of the description by itself. Please notice that default implementation of setShortDescription will fire the change by itself.

fireIconChange

protected final void fireIconChange()

Fire a change event for PROP_ICON.

fireOpenedIconChange

protected final void fireOpenedIconChange()

Fire a change event for PROP_OPENED_ICON.

fireNodeDestroyed

protected final void fireNodeDestroyed()

To all node listeners fire node destroyed notification.

firePropertySetsChange

protected final void firePropertySetsChange(Node.PropertySet[] o,
                                            Node.PropertySet[] n)

Fires a (Bean) property change event (for PROP_PROPERTY_SETS).

Parameters:

o - the old set

n - the new set

fireCookieChange

protected final void fireCookieChange()

Fires a change event for PROP_COOKIE. The old and new values are set to null.

toString

public String toString()

Overrides:

toString in class Object