dsto.dfc.swing.commands
Class CommandViewNode

java.lang.Object
  dsto.dfc.swing.commands.CommandViewNode

public final class CommandViewNode
extends Object

A node used to build the merged command trees used by CommandView's.

WARNING: complicated attempt to explain the approach follows. You don't need to understand this to use command views, it's included only to provide convincing evidence of how clever I've been here.

Each node has zero or more 'references' (identified by Reference instances stored in the references set). These references identify what node(s) from which subtrees have been merged to form this node and also define this node's position in its parent.

Each reference has a major index (assigned by the CommandView owning the tree) and a minor index (the index of the reference's source node in its parent). This forms a two-level indexing scheme where 1.1 is 'lower' than 1.2, 1.5 is lower than 2.1, etc (see Reference#compareTo). A node's children are always maintained in sorted order defined by their lowest reference within their parent as references are added/removed.

Each node also has zero or more Command's associated with it (nodes with no command are typically 'grouping' nodes). In the case where more than one command is associated with a node (eg in the case where two merged subtrees contain the same logical command such as 'edit.Copy'), this is termed command overloading. Overloading is resolved by defining the top command on the 'commands' stack as the active command. The active command is automatically updated to be the command associated with the last subnode reference added to this node. A client may also elect to 'activate' a certain command by causing it to pop to the top of the stack (see setCommand(dsto.dfc.swing.commands.Command) and CommandView.activate()).

Version:

$Revision$

Author:

Matthew

See Also:

Command, CommandView

Constructor Summary

CommandViewNode()
Create a root node.

CommandViewNode(CommandViewNode parent, Command command)
Create a node with a given name and an associated command.

CommandViewNode(CommandViewNode parent, String name)
Create a node with a given name and no associated command.

Method Summary

void	addCommandViewNodeListener(CommandViewNodeListener l)
void	connectParent() Connect this node to its parent (ie add to child list).
CommandViewNode	findChild(String childName) Find a child with a matching logical name.
CommandViewNode	findRoot() Find the root for this node.
protected void	fireChildAdded(CommandViewNodeEvent e)
protected void	fireChildMoved(CommandViewNodeEvent e)
protected void	fireChildRemoved(CommandViewNodeEvent e)
protected void	fireCommandChanged(CommandViewNodeEvent e)
CommandViewNode	followNamePath(CommandViewNode node) Find the equivalent node in this tree for a node in another tree.
CommandViewNode	getChild(int index) Get the child at a given index.
int	getChildCount() The number of children of this node.
Command	getCommand() The currently active command (may be null if no command is associated with this node).
int	getIndex() The node's index in its parent (-1 if not contained within parent or parent is null).
String	getName() The logical name for this node which is unique within parent namespace.
CommandViewNode	getParent() The node's parent.
CommandViewNode	mergeChild(CommandViewNode refNode, int majorIndex, int minorIndex) Merge a reference subnode as a child of this node.
CommandViewNode	remergeMinorIndex(CommandViewNode refNode, int newMinorIndex) 'Remerge' an already exisiting subnode reference with a new minor index.
void	removeCommandViewNodeListener(CommandViewNodeListener l)
void	setCommand(Command newCommand) Set the currently active command.
void	shiftMajorIndexes(int startIndex, int delta) Used by command view to adjust the major indexes of all subnode references.
String	toString()
CommandViewNode	unmergeChild(CommandViewNode refNode) Reverse the effect of mergeChild().

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandViewNode

public CommandViewNode()

Create a root node.

CommandViewNode

public CommandViewNode(CommandViewNode parent,
                       String name)

Create a node with a given name and no associated command.

Parameters:

parent - The node's parent. The new node will not be automatically added to the parent's child list (see connectParent ()).

name - The logical name for the node.

CommandViewNode

public CommandViewNode(CommandViewNode parent,
                       Command command)

Create a node with a given name and an associated command.

Parameters:

parent - The node's parent. The new node will not be automatically added to the parent's child list (see connectParent()).

command - The initial command for the node (command.getName()) becomes the node's name).

Method Detail

connectParent

public void connectParent()

Connect this node to its parent (ie add to child list).

getName

public String getName()

The logical name for this node which is unique within parent namespace.

getCommand

public Command getCommand()

The currently active command (may be null if no command is associated with this node).

setCommand

public void setCommand(Command newCommand)

Set the currently active command.

getParent

public CommandViewNode getParent()

The node's parent.

getIndex

public int getIndex()

The node's index in its parent (-1 if not contained within parent or parent is null).

getChildCount

public int getChildCount()

The number of children of this node.

getChild

public CommandViewNode getChild(int index)
                         throws IndexOutOfBoundsException

Get the child at a given index.

Throws:

IndexOutOfBoundsException - if index is not valid (>= 0 and < getChildCount ()).

findChild

public CommandViewNode findChild(String childName)

Find a child with a matching logical name.

Parameters:

childName - The logical name to search for.

Returns:

The matching child or null if not found.

followNamePath

public CommandViewNode followNamePath(CommandViewNode node)

Find the equivalent node in this tree for a node in another tree. Approach is to follow node to its parent, and then follow the same path back upwards starting from this node.

Parameters:

node - The end node of the path.

Returns:

The node, using this node as root, that is equivalent to node (will either be this node or a child).

findRoot

public CommandViewNode findRoot()

Find the root for this node.

mergeChild

public CommandViewNode mergeChild(CommandViewNode refNode,
                                  int majorIndex,
                                  int minorIndex)

Merge a reference subnode as a child of this node.

Parameters:

refNode - The subnode to merge.

majorIndex - The major index of the new reference.

minorIndex - The minor index of the new reference.

Returns:

The child node that was created/updated for the subnode.

See Also:

unmergeChild(dsto.dfc.swing.commands.CommandViewNode)

unmergeChild

public CommandViewNode unmergeChild(CommandViewNode refNode)

Reverse the effect of mergeChild().

Parameters:

refNode - The reference subnode to remove.

Returns:

The child node that was updated.

See Also:

mergeChild(dsto.dfc.swing.commands.CommandViewNode, int, int)

remergeMinorIndex

public CommandViewNode remergeMinorIndex(CommandViewNode refNode,
                                         int newMinorIndex)

'Remerge' an already exisiting subnode reference with a new minor index.

Parameters:

refNode - The reference subnode to update.

newMinorIndex - The new minor index for the reference.

Returns:

The child node that was updated.

See Also:

mergeChild(dsto.dfc.swing.commands.CommandViewNode, int, int)

shiftMajorIndexes

public void shiftMajorIndexes(int startIndex,
                              int delta)

Used by command view to adjust the major indexes of all subnode references. This must NOT change the relative ordering of the references.

Parameters:

startIndex - The lower bound (inclusive) of the indexes to change.

delta - The amount to change the indexes by.

See Also:

CommandView.addView(dsto.dfc.swing.commands.CommandView), CommandView.removeView(dsto.dfc.swing.commands.CommandView)

removeCommandViewNodeListener

public void removeCommandViewNodeListener(CommandViewNodeListener l)

addCommandViewNodeListener

public void addCommandViewNodeListener(CommandViewNodeListener l)

fireChildAdded

protected void fireChildAdded(CommandViewNodeEvent e)

fireChildRemoved

protected void fireChildRemoved(CommandViewNodeEvent e)

fireChildMoved

protected void fireChildMoved(CommandViewNodeEvent e)

fireCommandChanged

protected void fireCommandChanged(CommandViewNodeEvent e)

toString

public String toString()

Overrides:

toString in class Object