oracle.ide.panels
Class Navigable

java.lang.Object
  oracle.ide.panels.MetaTraversable
      oracle.ide.panels.Navigable

All Implemented Interfaces:

Copyable

Direct Known Subclasses:

DetailNavigable, KeyStrokesConfigUI, ProjectContentNavigable

public class Navigable
extends MetaTraversable

Each instance of the Navigable class represents a single tree node. Clicking on that tree node brings up the UI corresponding to the associated Traversable.

A Navigable instance is responsible for building part of the tree structure through its createTreeNode(NavigableContext) method. This allows a particular Navigable implementation to provide for more complex ways of determining the structure of its subtree.

Subclasses with additional member fields will also need to override the copyTo(Object) and copyToImpl(Navigable) methods in order to maintain correct copying behavior. Without the right copying behavior, a Navigable subclass will not cooperate properly with a NavigableRegistry.

Nested Class Summary

static class

Navigable.NavigableComparator Comparator implementation used for sorting child Navigable instances by label.

Field Summary

static int	BOLD
static java.lang.String	DEFAULT_CHILD_COMPARATOR_KEY The key to use for looking up the default Navigable.NavigableComparator in a NavigableContext; the Comparator is used for sorting Navigable children during a call to createTreeNode(NavigableContext).
static int	ITALIC
static java.util.Comparator	NAVIGABLE_COMPARATOR A standard Navigable.NavigableComparator that sorts Navigable instances by the short label.
static int	PLAIN

Constructor Summary

protected	Navigable() Should only be used by copyTo(Object).
protected	Navigable(java.lang.String shortLabel) Creates a new Navigable with the specified label.
	Navigable(java.lang.String shortLabel, java.lang.Class traversableClass) Creates a new Navigable with the specified label and Traversable class.
	Navigable(java.lang.String shortLabel, java.lang.Class traversableClass, java.lang.Class[] constructorArgTypes, java.lang.Object[] constructorArgs, Navigable[] childNavigables)
	Navigable(java.lang.String shortLabel, java.lang.Class traversableClass, Navigable[] childNavigables) Creates a new Navigable with the specified label, Traversable class, and array of child Navigables.

Method Summary

void	addChildNavigable(Navigable childNavigable) Adds a new Navigable to the array of child Navigables.
protected void	appendChildNavigables(javax.swing.tree.DefaultMutableTreeNode parent, NavigableContext nc) This method calls getChildNavigables() to get the list of child Navigable objects.
protected void	appendChildNodes(javax.swing.tree.DefaultMutableTreeNode parent, Navigable[] children, NavigableContext nc) This method invokes createTreeNode(NavigableContext) on each Navigable specified in children and adds the resulting DefaultMutableTreeNode (if it is not null) to the parent.
protected void	appendDetailNavigables(javax.swing.tree.DefaultMutableTreeNode parent, NavigableContext nc) This method calls getDetailNavigables() to get the list of detail Navigable objects.
java.lang.Object	copyTo(java.lang.Object target) Subclasses must override this method if new member fields are introduced.
protected void	copyToImpl(Navigable copy) Subclasses must implement an appropriate variant of this method if new member fields are introduced.
javax.swing.tree.DefaultMutableTreeNode	createDetailRootNode(NavigableContext nc) When the Navigable is used to show detail nodes in a separate tree, this method is used to construct the detail tree, using the returned tree node as the root of the detail tree; in general, only NavigableUIContainer implementations should call this method directly.
javax.swing.tree.DefaultMutableTreeNode	createTreeNode(NavigableContext nc) This method constructs a DefaultMutableTreeNode that is to represent the Navigable in the tree; in general, only NavigableUIContainer implementations should call this method directly.
protected javax.swing.tree.DefaultMutableTreeNode	createTreeNodeImpl(NavigableContext nc) This method is the essential method in which a tree node that represents a Navigable is created.
protected java.util.Comparator	getChildComparator() Fetch the comparator to use for sorting the child navigables.
protected Navigable[]	getChildNavigables() By default, this returns the child Navigables that were set when this DefaultNavigable was constructed.
Navigable[]	getChildren()
protected Navigable[]	getDetailNavigables() Returns null by default.
int	getDisplayStyle()
javax.swing.Icon	getIcon() This implementation always returns null.
java.lang.String	getLongLabel() This implementation simply invokes return getShortLabel().
java.lang.String	getRawShortLabel() This method returns the entire short label string, including any occurrance of the mnemonic character, &.
java.lang.String	getShortLabel() This implementation returns the short label that was specified when this Navigable was created.
java.lang.String	getToolTipText() This implementation always returns null.
boolean	includeInDefault()
protected boolean	mayHaveChildren(NavigableContext nc) Overridable method to determine whether a Navigable may have children such that a + may be shown next to it in the tree.
void	setChildComparator(java.util.Comparator customComparator) Sets whether the child navigables are sorted or not.
protected void	setChildNavigables(Navigable[] childNavigables) Accessor for the private data member that stores the current child Navigables.
protected void	setDataScope(Namespace dataScope) Sets the specified Namespace as the data scope for this Navigable.
void	setDisplayStyle(int displayStyle)
void	setShortLabel(java.lang.String shortLabel)
protected static Navigable[]	sortNavigables(Navigable[] navigables, java.util.Comparator comparator) Sorts the specified Navigable array using the specified Navigable.NavigableComparator, and returns a sorted version of the array.
java.lang.String	toString()

Methods inherited from class oracle.ide.panels.MetaTraversable

copyToImpl, findHelpID, getTraversableClass, isUsingTraversableDefaultConstructor, newTraversable, newTraversable, setHelpID, setNameLink

Methods inherited from class java.lang.Object

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

Field Detail

PLAIN

public static final int PLAIN

See Also:

Constant Field Values

BOLD

public static final int BOLD

See Also:

Constant Field Values

ITALIC

public static final int ITALIC

See Also:

Constant Field Values

DEFAULT_CHILD_COMPARATOR_KEY

public static final java.lang.String DEFAULT_CHILD_COMPARATOR_KEY

The key to use for looking up the default Navigable.NavigableComparator in a NavigableContext; the Comparator is used for sorting Navigable children during a call to createTreeNode(NavigableContext).

See Also:

Constant Field Values

NAVIGABLE_COMPARATOR

public static final java.util.Comparator NAVIGABLE_COMPARATOR

A standard Navigable.NavigableComparator that sorts Navigable instances by the short label.

Constructor Detail

Navigable

protected Navigable(java.lang.String shortLabel)

Creates a new Navigable with the specified label. There is no associated Traversable class, and the Navigable has no children. In general, this constructor will be called by a subclass that overrides MetaTraversable.newTraversable(ApplyNotifier), getChildNavigables(), and/or getDetailNavigables().

Parameters:

shortLabel - The short label to display when rendering the UI for the Navigable.

Navigable

public Navigable(java.lang.String shortLabel,
                 java.lang.Class traversableClass)

Creates a new Navigable with the specified label and Traversable class. The Navigable has no children unless a subclass implementation provides them.

Parameters:

shortLabel - The short label to display when rendering the UI for the Navigable.

traversableClass - The Class of the Traversable associated with this Navigable. Since many usages of Navigable do not require any parameters when instantiating the Traversable, this is provided as a convenience. Note that if the Traversable class implements the ApplyListener interface, instances will be added as an ApplyListener to the ApplyNotifier linked to the NavigableUIContainer.

See Also:

#newTraversable(ApplyNotifier)}.

Navigable

public Navigable(java.lang.String shortLabel,
                 java.lang.Class traversableClass,
                 Navigable[] childNavigables)

Creates a new Navigable with the specified label, Traversable class, and array of child Navigables.

Parameters:

shortLabel - The short label to display when rendering the UI for the Navigable.

traversableClass - The Class of the Traversable associated with this Navigable. Since many usages of Navigable do not require any parameters when instantiating the Traversable, this is provided as a convenience. See MetaTraversable.newTraversable(ApplyNotifier).

childNavigables - An array of the children of this Navigable. This parameter may be null if there are no children.

Navigable

public Navigable(java.lang.String shortLabel,
                 java.lang.Class traversableClass,
                 java.lang.Class[] constructorArgTypes,
                 java.lang.Object[] constructorArgs,
                 Navigable[] childNavigables)

Navigable

protected Navigable()

Should only be used by copyTo(Object).

Method Detail

copyTo

public java.lang.Object copyTo(java.lang.Object target)

Subclasses must override this method if new member fields are introduced. See Copyable for details.

Specified by:

copyTo in interface Copyable

Overrides:

copyTo in class MetaTraversable

Parameters:

target - The target object to which the state of this object should be copied. If target is null, then the copyTo method will return a new instance of this class.

Returns:

The object to which the state of this object was copied. If the target was non-null, then the return value is the same as the target object that was passed in; otherwise, the return value is a new instance of this class.

See Also:

Copyable.copyTo(Object)

copyToImpl

protected final void copyToImpl(Navigable copy)

Subclasses must implement an appropriate variant of this method if new member fields are introduced. Note that the type of the argument is exactly the type of the implementing class. The subclass will need to follow suit and implement a method with signature:

protected final void copyToImpl( copy );

Then, the subclass implementation must first delegate to this method with a call to:

super.copyToImpl( copy );

This ensures that the copyTo(Object) method instantiates the correct class when the target is null and also provides an extendable way of implementing copying behavior.

Parameters:

copy - The Navigable to which this Navigable's state should be copied.

getShortLabel

public java.lang.String getShortLabel()

This implementation returns the short label that was specified when this Navigable was created. If the mnemonic character & was present in the short label, this implementation will strip that character out of the returned string.

getRawShortLabel

public java.lang.String getRawShortLabel()

This method returns the entire short label string, including any occurrance of the mnemonic character, &. Use getShortLabel instead if a short label stripped of & is required.

Returns:

Entire short label of the Navigable, including any & character.

getLongLabel

public java.lang.String getLongLabel()

This implementation simply invokes return getShortLabel().

getIcon

public javax.swing.Icon getIcon()

This implementation always returns null.

getToolTipText

public java.lang.String getToolTipText()

This implementation always returns null.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getDisplayStyle

public int getDisplayStyle()

setDisplayStyle

public void setDisplayStyle(int displayStyle)

setShortLabel

public void setShortLabel(java.lang.String shortLabel)

setChildComparator

public void setChildComparator(java.util.Comparator customComparator)

Sets whether the child navigables are sorted or not. If the comparator is provided, the child navigables will be sorted. Otherwise, they will be unsorted. The comparator should be immutable, as it may be passed directly to a copy of this Navigable instance.

Parameters:

customComparator - comparator to use for sorting, null to disable sorting

getChildComparator

protected java.util.Comparator getChildComparator()

Fetch the comparator to use for sorting the child navigables.

Returns:

the comparator to use for sorting the children

getChildren

public Navigable[] getChildren()

Returns:

an array of child Navigables for this Navigable

createTreeNode

public javax.swing.tree.DefaultMutableTreeNode createTreeNode(NavigableContext nc)

This method constructs a DefaultMutableTreeNode that is to represent the Navigable in the tree; in general, only NavigableUIContainer implementations should call this method directly. Subclasses may, of course, override the behavior.

The user object of the returned tree node (and all its descendant nodes) must be an instance of Navigable.

If the return value is null, the Navigable is omitted from the tree.

Note: this method returns DefaultMutableTreeNode instead of just MutableTreeNode because the getUserObject(...) method is not specified by MutableTreeNode.

Parameters:

nc - The NavigableContext in which this Navigable should render the tree node.

Returns:

The tree node which is to represent this Navigable.

createDetailRootNode

public javax.swing.tree.DefaultMutableTreeNode createDetailRootNode(NavigableContext nc)

When the Navigable is used to show detail nodes in a separate tree, this method is used to construct the detail tree, using the returned tree node as the root of the detail tree; in general, only NavigableUIContainer implementations should call this method directly. Subclasses may, of course, override the behavior.

The root is not actually displayed in the detail tree, so the user object associated with the root is not important. However, all descendants of the returned root must also be instances of DefaultMutableTreeNode whose user objects are instances of Navigable.

It is important that this method return a non-null value, even if there are no detail root nodes.

Parameters:

nc - The NavigableContext in which this Navigable should render the tree node.

Returns:

The tree node which represents the root of the detail tree. If the Navigable has no detail nodes, then this method must return an empty tree node.

addChildNavigable

public void addChildNavigable(Navigable childNavigable)

Adds a new Navigable to the array of child Navigables.

Parameters:

The - child Navigable to add.

includeInDefault

public boolean includeInDefault()

setDataScope

protected void setDataScope(Namespace dataScope)

Sets the specified Namespace as the data scope for this Navigable. This method must be called at some point before a Navigable is used in a UI container.

This is a transient property, so it will not be copied in the copyTo(Object) or copyToImpl(Navigable) method.

Parameters:

dataScope - The Namespace that represents the data scope for this Navigable.

getChildNavigables

protected Navigable[] getChildNavigables()

By default, this returns the child Navigables that were set when this DefaultNavigable was constructed. Subclasses can override this method to specify a custom list of children. The result of this method is used by appendChildNavigables(...) to append child nodes.

Returns:

The child Navigables of this Navigable.

setChildNavigables

protected void setChildNavigables(Navigable[] childNavigables)

Accessor for the private data member that stores the current child Navigables.

Parameters:

The - child Navigables to associate with this Navigable.

getDetailNavigables

protected Navigable[] getDetailNavigables()

Returns null by default. Subclasses should override this method in order to specify a list of detail Navigables. The result of this method is used by appendDetailNavigables(DefaultMutableTreeNode, NavigableContext) to append detail nodes.

Returns:

An array of Navigables representing the detail for this Navigable. Detail nodes are uncommonly used, so in order to specify detail nodes, a subclass must override this method's implementation in order to provide a return value other than null.

createTreeNodeImpl

protected javax.swing.tree.DefaultMutableTreeNode createTreeNodeImpl(NavigableContext nc)

This method is the essential method in which a tree node that represents a Navigable is created. It is called from createTreeNode(NavigableContext). This implementation has been separated to express a specific step in the Template Method design pattern for creating a Navigable tree node.

Parameters:

nc - The NavigableContext in which this Navigable should render the tree node.

Returns:

The tree node which represents the root of the detail tree. If the Navigable has no detail nodes, then this method must return an empty tree node.

appendChildNavigables

protected void appendChildNavigables(javax.swing.tree.DefaultMutableTreeNode parent,
                                     NavigableContext nc)

This method calls getChildNavigables() to get the list of child Navigable objects. Then this method calls appendChildNodes to append the child Navigables to the specified parent.

Parameters:

parent - The node to which the child nodes will be added.

nc - The NavigableContext in which this Navigable should render the child tree nodes.

appendChildNodes

protected void appendChildNodes(javax.swing.tree.DefaultMutableTreeNode parent,
                                Navigable[] children,
                                NavigableContext nc)

This method invokes createTreeNode(NavigableContext) on each Navigable specified in children and adds the resulting DefaultMutableTreeNode (if it is not null) to the parent.

Parameters:

parent - The node to which the child nodes will be added.

children - The child Navigables whose DefaultMutableTreeNode representations are to be added to the parent.

nc - The NavigableContext in which this Navigable should render its tree nodes.

appendDetailNavigables

protected void appendDetailNavigables(javax.swing.tree.DefaultMutableTreeNode parent,
                                      NavigableContext nc)

This method calls getDetailNavigables() to get the list of detail Navigable objects. Then this method calls appendChildNodes to append the detail Navigables to the specified parent.

Parameters:

parent - The node to which the detail nodes will be added.

nc - The NavigableContext in which this Navigable should render its tree nodes.

sortNavigables

protected static Navigable[] sortNavigables(Navigable[] navigables,
                                            java.util.Comparator comparator)

Sorts the specified Navigable array using the specified Navigable.NavigableComparator, and returns a sorted version of the array. The input array is never modified; if the array might need sorting, a copy of the array is sorted and returned instead.

mayHaveChildren

protected boolean mayHaveChildren(NavigableContext nc)

Overridable method to determine whether a Navigable may have children such that a + may be shown next to it in the tree. Implementations can override this when the result is known a priori and a call to getChildNavigables() could be expensive. The test should include detail Navigable instances as well if the NavigableContext specifies that detail nodes should be shown as children

Parameters:

nc - The NavigableContext used to determine the context of the check

Returns:

true if the navigable may have children