dsto.dfc.swing.commands
Class CommandView

java.lang.Object
  dsto.dfc.util.BasicPropertyEventSource
      dsto.dfc.swing.commands.CommandView

All Implemented Interfaces:

Copyable, JavaBean, PropertyEventSource, Serializable, Cloneable

public class CommandView
extends BasicPropertyEventSource
implements Serializable

A list of Command's and sub-CommandView's intended to define the commands presented in a given UI context, such as a main menu or a toolbar. See CommandMenus and CommandToolBars for examples of how to present command views in a UI. The internal implementation manages a tree of CommandViewNode's representing the merged commands both from this view and the commands from child command views.

An object (usually a Component) that wishes to export a set of commands for inclusion in a main menu, toolbar, etc will implement the CommandSource interface and export CommandView's with the appropriate commands (and any command views, including those originating from any contained components).

Version:

$Revision$

See Also:

CommandSource, Command, CommandMenus, CommandToolBars, Serialized Form

Field Summary

static String	CONTEXT_MENU_VIEW
static String	MAIN_MENU_VIEW
static String	TOOLBAR_VIEW

Constructor Summary

CommandView(String viewName)
Create a new command view.

Method Summary

void	activate() Logically active this view, bringing any of its overloaded commands to the 'top', making them active.
protected void	activateSubtree(CommandViewNode root, CommandViewNode subRoot)
void	addCommand(Command command) Add a command to the end of the view.
void	addCommand(Command command, int index) Add a command to the view at a specific index.
void	addCommands(Collection commands)
protected void	addEntry(Object entry, CommandViewNode rootNode, int index)
void	addGroup(String group)
void	addGroup(String group, int index) Add an empty command group to the view.
void	addView(CommandView view) Add a child command view to this view.
void	addView(CommandView view, int index) Add a child command view with a specific index.
void	clearCommandProperties() Remove all command client properties.
protected void	commandPropertyChanged(PropertyChangeEvent e)
boolean	containsCommand(Command command)
boolean	containsGroup(String group)
boolean	containsView(CommandView subView)
Command	findCommand(String commandName) Find the first instance of a command with a matching name in a breadth-first search of subviews.
CommandView	findViewForCommand(String commandName) Find the first view in a breadth-first search of subviews that contains a command with a matching name.
Command	getCommand(Class commandClass)
Command	getCommand(int index) Get the command at a given ordinal.
Command	getCommand(String commandName)
Object	getCommandProperty(String commandName, Object key) Get a client property for a command.
boolean	getCommandProperty(String commandName, Object key, boolean defaultValue) Get a boolean client property for a command.
Object	getCommandProperty(String commandName, Object key, Object defaultValue) Get a client property for a command.
Command	getDefaultCommand()
Object	getEntry(int index) Get the the entry at a given index in the view.
int	getEntryCount() The number of entries (views and commands in this view).
int	getIndex(Command command)
int	getIndex(CommandView view) Get the index associated with a sub view a CommandView.
protected int	getMajorIndex(CommandViewNode node) Get the index associated with a node of a subtree contained in this view.
CommandViewNode	getTreeRoot() The root of the merged command tree.
CommandView	getView(int index) Get the command at a given ordinal.
String	getViewName()
protected CommandViewNode	makeVine(String group)
protected CommandViewNode	makeVine(String group, Command command) Make a vine (tree where all nodes have at most one child) from a command.
protected void	merge(CommandViewNode parent, CommandViewNode subtreeNode, int majorIndex) Merge (mount) a subtree node and all its children onto a node of this tree.
protected void	remergeMinorIndex(CommandViewNode parent, CommandViewNode subtreeNode) Remerge a subtree node and all its children with a changed minor index.
void	removeAll() Remove all commands and command views from this view.
void	removeCommand(Class commandClass)
void	removeCommand(Command command)
Command	removeCommand(String commandName)
void	removeCommands(Collection commands)
protected void	removeEntry(Object entry)
protected void	removeEntry(Object entry, int index)
void	removeGroup(String group)
void	removeView(CommandView view) Remove a child command view.
void	setCommandProperty(String commandName, Object key, Object value) Set a client property for a command.
void	setDefaultCommand(Command newValue) The default command for this view.
protected void	shiftMajorIndexes(CommandViewNode node, int startIndex, int delta) Shift all the major indicies of nodes of a tree by a given amount.
protected void	subtreeChildAdded(CommandViewNodeEvent e)
protected void	subtreeChildMoved(CommandViewNodeEvent e)
protected void	subtreeChildRemoved(CommandViewNodeEvent e)
protected void	subtreeCommandChanged(CommandViewNodeEvent e)
protected void	unmerge(CommandViewNode parent, CommandViewNode subtreeNode) Reverse the effect of merge ().
protected void	updateCommandGroup(Command command) Updates command tree when a command changes its group.
protected void	viewPropertyChanged(PropertyChangeEvent e)

Methods inherited from class dsto.dfc.util.BasicPropertyEventSource

addPropertyChangeListener, clone, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeSource, removePropertyChangeListener, setPropertyChangeSource

Methods inherited from class java.lang.Object

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

Field Detail

MAIN_MENU_VIEW

public static final String MAIN_MENU_VIEW

See Also:

Constant Field Values

CONTEXT_MENU_VIEW

public static final String CONTEXT_MENU_VIEW

See Also:

Constant Field Values

TOOLBAR_VIEW

public static final String TOOLBAR_VIEW

See Also:

Constant Field Values

Constructor Detail

CommandView

public CommandView(String viewName)

Create a new command view.

Parameters:

viewName - The view name (usually one of MAIN_MENU_VIEW, CONTEXT_MENU_VIEW or TOOLBAR_VIEW).

Method Detail

getViewName

public String getViewName()

getDefaultCommand

public Command getDefaultCommand()

setDefaultCommand

public void setDefaultCommand(Command newValue)

The default command for this view. Some UI controls, such as context menus, will execute this command by default, when the user executes an action such as double-clicking an item.

setCommandProperty

public void setCommandProperty(String commandName,
                               Object key,
                               Object value)

Set a client property for a command.

Parameters:

commandName - The command's name (eg as obtained by getName ()).

key - The property key.

value - The property value.

See Also:

getCommandProperty(String,Object,Object)

getCommandProperty

public boolean getCommandProperty(String commandName,
                                  Object key,
                                  boolean defaultValue)

Get a boolean client property for a command.

Parameters:

commandName - The command's name (eg as obtained by getName ()).

key - The property key.

defaultValue - The value to return if property is not set.

Returns:

The property value, or null if not found. If the property is not set in this view sub views are also searched.

Throws:

ClassCastException - if the property exists but is not boolean.

See Also:

setCommandProperty(java.lang.String, java.lang.Object, java.lang.Object)

getCommandProperty

public Object getCommandProperty(String commandName,
                                 Object key,
                                 Object defaultValue)

Get a client property for a command.

Parameters:

commandName - The command's name (eg as obtained by getName ()).

key - The property key.

defaultValue - The value to return if property is not set.

Returns:

The property value, or null if not found. If the property is not set in this view sub views are also searched.

See Also:

setCommandProperty(java.lang.String, java.lang.Object, java.lang.Object)

getCommandProperty

public Object getCommandProperty(String commandName,
                                 Object key)

Get a client property for a command.

Parameters:

commandName - The command's name (eg as obtained by getName ()).

key - The property key.

Returns:

The property value, or null if not found. If the property is not set in this view sub views are also searched.

See Also:

setCommandProperty(java.lang.String, java.lang.Object, java.lang.Object)

clearCommandProperties

public void clearCommandProperties()

Remove all command client properties.

See Also:

setCommandProperty(java.lang.String, java.lang.Object, java.lang.Object)

findViewForCommand

public CommandView findViewForCommand(String commandName)

Find the first view in a breadth-first search of subviews that contains a command with a matching name.

Parameters:

commandName - The name of the command.

Returns:

The command view that the command was found in, or null if not found.

findCommand

public Command findCommand(String commandName)

Find the first instance of a command with a matching name in a breadth-first search of subviews.

activate

public void activate()

Logically active this view, bringing any of its overloaded commands to the 'top', making them active. See WindowFocusTracker for an example of resolving overloaded commands (via input focus) using this facility.

getTreeRoot

public CommandViewNode getTreeRoot()

The root of the merged command tree.

containsView

public boolean containsView(CommandView subView)

containsCommand

public boolean containsCommand(Command command)

containsGroup

public boolean containsGroup(String group)

addView

public void addView(CommandView view)

Add a child command view to this view.

addView

public void addView(CommandView view,
                    int index)

Add a child command view with a specific index.

removeView

public void removeView(CommandView view)

Remove a child command view.

addCommand

public void addCommand(Command command)

Add a command to the end of the view.

addCommands

public void addCommands(Collection commands)

removeCommands

public void removeCommands(Collection commands)

removeAll

public void removeAll()

Remove all commands and command views from this view.

addCommand

public void addCommand(Command command,
                       int index)

Add a command to the view at a specific index.

removeCommand

public void removeCommand(Command command)

removeCommand

public Command removeCommand(String commandName)

addGroup

public void addGroup(String group)

See Also:

addGroup(String,int)

addGroup

public void addGroup(String group,
                     int index)

Add an empty command group to the view. This can be used to impose command orderings other than the default. For example, to force all commands in the 'file.cut_and_paste' group to occur first in the command view, the 'file.cut_and_paste' group could be added at index 0.

removeGroup

public void removeGroup(String group)

getCommand

public Command getCommand(String commandName)

removeCommand

public void removeCommand(Class commandClass)

getCommand

public Command getCommand(Class commandClass)

getEntryCount

public int getEntryCount()

The number of entries (views and commands in this view).

getCommand

public Command getCommand(int index)
                   throws IndexOutOfBoundsException,
                          ClassCastException

Get the command at a given ordinal.

Throws:

IndexOutOfBoundsException - if index is not valid.

ClassCastException - if entry at index is not a command.

getView

public CommandView getView(int index)
                    throws IndexOutOfBoundsException,
                           ClassCastException

Get the command at a given ordinal.

Throws:

IndexOutOfBoundsException - if index is not valid.

ClassCastException - if entry at index is not a command.

getEntry

public Object getEntry(int index)

Get the the entry at a given index in the view.

Parameters:

index - The index of the entry.

Returns:

The entry (either a Command or a CommandView).

getIndex

public int getIndex(CommandView view)

Get the index associated with a sub view a CommandView.

getIndex

public int getIndex(Command command)

getMajorIndex

protected int getMajorIndex(CommandViewNode node)

Get the index associated with a node of a subtree contained in this view.

Parameters:

node - A node from a direct subtree of this view.

Returns:

The index of the entry (command or view) that it corresponds to.

shiftMajorIndexes

protected void shiftMajorIndexes(CommandViewNode node,
                                 int startIndex,
                                 int delta)

Shift all the major indicies of nodes of a tree by a given amount.

Parameters:

node - The root of the tree.

startIndex - The lower bound of indexes to change.

delta - The amount to shift the index by.

See Also:

CommandViewNode.shiftMajorIndexes(int, int)

makeVine

protected CommandViewNode makeVine(String group,
                                   Command command)

Make a vine (tree where all nodes have at most one child) from a command.

Parameters:

group - The group to place the command in.

command - The command.

Returns:

The root of the new vine.

makeVine

protected CommandViewNode makeVine(String group)

addEntry

protected void addEntry(Object entry,
                        CommandViewNode rootNode,
                        int index)

removeEntry

protected void removeEntry(Object entry)

removeEntry

protected void removeEntry(Object entry,
                           int index)

merge

protected void merge(CommandViewNode parent,
                     CommandViewNode subtreeNode,
                     int majorIndex)

Merge (mount) a subtree node and all its children onto a node of this tree.

Parameters:

parent - The parent of the new merged node.

subtreeNode - The subtree node to merge into a child of parent.

majorIndex - The major index to associate with the merge.

See Also:

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

unmerge

protected void unmerge(CommandViewNode parent,
                       CommandViewNode subtreeNode)

Reverse the effect of merge ().

Parameters:

parent - The parent of the merged node.

subtreeNode - The subtree node that should be unmerged.

remergeMinorIndex

protected void remergeMinorIndex(CommandViewNode parent,
                                 CommandViewNode subtreeNode)

Remerge a subtree node and all its children with a changed minor index. May be used when the subtreeNode has changed position in its parent.

Parameters:

parent - The parent of the merged node.

subtreeNode - The subtree node.

See Also:

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

updateCommandGroup

protected void updateCommandGroup(Command command)

Updates command tree when a command changes its group.

activateSubtree

protected void activateSubtree(CommandViewNode root,
                               CommandViewNode subRoot)

commandPropertyChanged

protected void commandPropertyChanged(PropertyChangeEvent e)

viewPropertyChanged

protected void viewPropertyChanged(PropertyChangeEvent e)

subtreeChildAdded

protected void subtreeChildAdded(CommandViewNodeEvent e)

subtreeChildRemoved

protected void subtreeChildRemoved(CommandViewNodeEvent e)

subtreeChildMoved

protected void subtreeChildMoved(CommandViewNodeEvent e)

subtreeCommandChanged

protected void subtreeCommandChanged(CommandViewNodeEvent e)