com.pietschy.command.group
Class CommandGroup

java.lang.Object
  extended by com.pietschy.command.Command
      extended by com.pietschy.command.group.CommandGroup
All Implemented Interfaces:
Bindable, Identifiable
Direct Known Subclasses:
DelegatingToggleGroup, RecentFileList, ToggleGroup

public class CommandGroup
extends Command

Groups allow commands to be grouped together and act as factories for menus, toolbars and the like. The following is an example group configuration for a simple file menu. The example places an expansion point before the exit command. The expansion point will automatically insert a separator at before any commands it cotains.

  group!file-menu@face.text=_File
  group!file-menu@members=\
    new, \
    open, \
    save, \
    save-as, \
    expand(separatorBefore), \
    separator, \
    exit
 
To use this group in you code you simple create and bind it as the following example shows.
   CommandGroup group = new CommandGroup("file-menu");
   group.bind(commandContainer);

   JMenuItem menu = group.createMenu();
   AbstractButton button = group.createButton();
 
For more information on the binding options please refer to the CommandContainer documentation.

Expansion points allow the addition of new members at runtime to a predetermined position in the group. The content of an expansion point is managed using getExpansionPointBuilder().

Groups can also be programatically generated from scratch using getBuilder().


Field Summary
 
Fields inherited from class com.pietschy.command.Command
internalLog, PROPERTY_ENABLED, PROPERTY_VISIBLE
 
Constructor Summary
  CommandGroup()
          Creates a new anonymous instance.
protected CommandGroup(boolean loadConfiguration)
          Creates a new anonymous instance that conditionally invokes Command.loadConfiguration()
  CommandGroup(java.lang.String id)
          Creates a new instance with the specified id.
protected CommandGroup(java.lang.String id, boolean loadConfiguration)
          Creates a new anonymous instance with the specified id that conditionally invokes Command.loadConfiguration()
 
Method Summary
 void addGroupListener(GroupListener l)
          Adds a GroupListener to the group.
protected  void bindToContainer(CommandContainer container)
          Invoked to bind this instance to the specified command container.
 javax.swing.AbstractButton createButton(ButtonFactory factory, java.lang.String context)
          Creates a new button that displays a popup menu when clicked.
 javax.swing.AbstractButton createButton(ButtonFactory buttonFactory, java.lang.String context, MenuFactory menuFactory, java.lang.String popupContext)
          Creates a new button that displays a popup menu when clicked.
protected  MemberManager createMemberManager()
          Creates the member manager.
 javax.swing.JMenuBar createMenuBar()
          Creates a new menu bar.
 javax.swing.JMenuBar createMenuBar(MenuFactory factory)
          Creates a new menu bar.
 javax.swing.JMenuBar createMenuBar(java.lang.String context)
          Creates a new menu bar.
 javax.swing.JMenuBar createMenuBar(java.lang.String context, MenuFactory factory)
          Creates a new menu bar.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.lang.String context)
          Creates a new menu for the group that contains the group members.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.lang.String context, MenuFactory popupFactory, java.lang.String popupContext)
          Creates a new menu for the group that contains the group members.
 javax.swing.JPopupMenu createPopupMenu()
          Creates a popup menu.
 javax.swing.JPopupMenu createPopupMenu(MenuFactory factory, java.lang.String context)
          Creates a popup menu.
 javax.swing.JPopupMenu createPopupMenu(java.lang.String context)
          Creates a popup menu.
 javax.swing.JToolBar createToolBar()
          Creates a new toolbar.
 javax.swing.JToolBar createToolBar(java.lang.String context)
          Creates a new toolbar.
 javax.swing.JToolBar createToolBar(java.lang.String context, ToolbarFactory factory)
          Creates a toolbar using the specified facename for the toolbar and the specified toolbar factory for the buttons.
 javax.swing.JToolBar createToolBar(ToolbarFactory factory)
          Creates a new toolbar.
 GroupBuilder getBuilder()
          Gets the current builder for this group.
 ExpansionPointBuilder getExpansionPointBuilder()
          Gets the current expansion point builder for this group.
 int getMemberCount()
          Returns the number of realised members in this group.
 java.lang.String getMemberListSpec()
          Gets the member specification used to populate this group.
protected  MemberManager getMemberManager()
          Gets the member support for this group.
protected  java.lang.String getPopupContext(java.lang.String context)
          Gets the context to use for popups menus whose activators (i.e.
 boolean isAllowableMember(Command prospectiveMember)
          Checks if the specified Command can be added to this group.
 java.util.Iterator<GroupMember> memberIterator()
          Returns an iterator over this groups GroupMember instances.
protected  void rebuildMembersFromSpec()
          Rebuilds this groups members from the current member list specification.
 void removeGroupListener(GroupListener l)
          Removes a GroupListener from the group.
 void setMemberListSpec(java.lang.String memberListSpec)
          Sets this groups member list specification.
protected  void unbindFromContainer(CommandContainer container)
          Invoked to unbind this instance from the specified command container.
 void visit(GroupVisitor visitor)
          Visits this group.
 void visitMembers(GroupVisitor visitor)
          Visits just the members of this group.
 
Methods inherited from class com.pietschy.command.Command
addContainerPropertyListener, addFace, addHoverListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, attach, bind, bind, bind, buttonIterator, configureAppearance, configureAppearances, configureButtonAppearances, configureButtonStates, configureButtonStates, createButton, createButton, createButton, createComponent, createMenuItem, createMenuItem, createMenuItem, detach, doButtonAttachments, doButtonDetachments, faceExists, findBestFace, fireHoverEnded, fireHoverStarted, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlternativeFaceContexts, getButtonFactory, getButtonIn, getCommandContainer, getContainerProperty, getDefaultFace, getDefaultFace, getFace, getFace, getId, getMenuFactory, getProperty, getProperty, getPropertyNames, getToolbarFactory, isAnonymous, isAttachedTo, isBound, isEnabled, isVisible, loadConfiguration, notifyCommandContainerHierarchyChanged, putProperties, putProperty, rebind, removeContainerPropertyListener, removeHoverListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, requestFocusIn, setButtonFactory, setEnabled, setMenuFactory, setToolbarFactory, setVisible, toString, unbind, validateId
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CommandGroup

public CommandGroup()
Creates a new anonymous instance.


CommandGroup

public CommandGroup(java.lang.String id)
Creates a new instance with the specified id.

Parameters:
id - the group id.

CommandGroup

protected CommandGroup(boolean loadConfiguration)
Creates a new anonymous instance that conditionally invokes Command.loadConfiguration()

Parameters:
loadConfiguration - true to invoke Command.loadConfiguration() during the constructor, false otherwise.

CommandGroup

protected CommandGroup(java.lang.String id,
                       boolean loadConfiguration)
Creates a new anonymous instance with the specified id that conditionally invokes Command.loadConfiguration()

Parameters:
id - the group id.
loadConfiguration - true to invoke Command.loadConfiguration() during the constructor, false otherwise.
Method Detail

bindToContainer

protected void bindToContainer(CommandContainer container)
Description copied from class: Command
Invoked to bind this instance to the specified command container.

Specified by:
bindToContainer in class Command
Parameters:
container - the container to bind to.

unbindFromContainer

protected void unbindFromContainer(CommandContainer container)
Description copied from class: Command
Invoked to unbind this instance from the specified command container.

Specified by:
unbindFromContainer in class Command
Parameters:
container - the container to unbind from.

setMemberListSpec

public void setMemberListSpec(java.lang.String memberListSpec)
                       throws ParseException
Sets this groups member list specification. This will cause the group to rebuild all members and repopulate all components.

The specification string must be of the same editor as that used on the configuration files.

   group.setMemberListSpec("new, open, save, save-as, separator, exit");

Parameters:
memberListSpec - the memberlist specification string
Throws:
java.lang.NullPointerException - if the spec is null.
ParseException - if the specification string is invalid.

rebuildMembersFromSpec

protected void rebuildMembersFromSpec()
                               throws ParseException
Rebuilds this groups members from the current member list specification. * @throws ParseException

Throws:
ParseException

getMemberListSpec

public java.lang.String getMemberListSpec()
Gets the member specification used to populate this group. May be null if the specification has never been set.

Returns:
the member specification used to populate this group

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.lang.String context)
Creates a new menu for the group that contains the group members. This method calls Defaults.getPopupContext(String) to determine the face context for the popup members.

Overrides:
createMenuItem in class Command
Parameters:
factory - the factory to use.
context - the face context to use.
Returns:
a new JMenu

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.lang.String context,
                                            MenuFactory popupFactory,
                                            java.lang.String popupContext)
Creates a new menu for the group that contains the group members.

Parameters:
factory - the factory to use.
context - the face context to use.
popupFactory - the factory to use when creating the popup menu.
popupContext - the face context to use for the popup menu items.
Returns:
a new JMenu

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory,
                                               java.lang.String context)
Creates a new button that displays a popup menu when clicked. This method calls getPopupContext(String) to determine the face context for the popup members.

Overrides:
createButton in class Command
Parameters:
factory - the factory to use.
context - the face context to use.
Returns:
a new JButton

createButton

public javax.swing.AbstractButton createButton(ButtonFactory buttonFactory,
                                               java.lang.String context,
                                               MenuFactory menuFactory,
                                               java.lang.String popupContext)
Creates a new button that displays a popup menu when clicked. This method calls getPopupContext(String) to determine the face context for the popup members.

Parameters:
buttonFactory - the factory to use when creating the button.
context - the face context to use for the button.
menuFactory - the factory to use when creating the popup menu.
popupContext - the face context to use when creating the menu.
Returns:
a new JButton

getPopupContext

protected java.lang.String getPopupContext(java.lang.String context)
Gets the context to use for popups menus whose activators (i.e. the button) have the specified face. This method simply delegates to Defaults.getPopupContext(String). For example this method will return Face.TOOLBAR_POPUP if the parent context is Face.TOOLBAR.

Parameters:
context - the face context of the parent component.
Returns:
the face context to use for the popup items.

createPopupMenu

public javax.swing.JPopupMenu createPopupMenu()
Creates a popup menu.

Returns:
a popup menu.

createPopupMenu

public javax.swing.JPopupMenu createPopupMenu(java.lang.String context)
Creates a popup menu.

Parameters:
context - the face context to use.
Returns:
a new popup menu.

createPopupMenu

public javax.swing.JPopupMenu createPopupMenu(MenuFactory factory,
                                              java.lang.String context)
Creates a popup menu.

Parameters:
factory - the factory to use when creating the menu items.
context - the face context to use.
Returns:
a new popup menu for this group.

createToolBar

public javax.swing.JToolBar createToolBar()
Creates a new toolbar.

Returns:
a new toolbar.

createToolBar

public javax.swing.JToolBar createToolBar(ToolbarFactory factory)
Creates a new toolbar.

Parameters:
factory - to factory to use.
Returns:
a new toolbar.

createToolBar

public javax.swing.JToolBar createToolBar(java.lang.String context)
Creates a new toolbar.

Parameters:
context - the face context to use.
Returns:
a new toolbar.

createToolBar

public javax.swing.JToolBar createToolBar(java.lang.String context,
                                          ToolbarFactory factory)
Creates a toolbar using the specified facename for the toolbar and the specified toolbar factory for the buttons.

Parameters:
context - the face context to use
factory - the factory to use.
Returns:
a new toolbar.

createMenuBar

public javax.swing.JMenuBar createMenuBar()
Creates a new menu bar.

Returns:
a new menu bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(java.lang.String context)
Creates a new menu bar.

Parameters:
context - the face context to use.
Returns:
a new menu bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(MenuFactory factory)
Creates a new menu bar.

Parameters:
factory - the factory to use.
Returns:
a new menu bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(java.lang.String context,
                                          MenuFactory factory)
Creates a new menu bar.

Parameters:
context - the face context to use.
factory - the factory to use.
Returns:
a new menu bar.

getMemberCount

public int getMemberCount()
Returns the number of realised members in this group. Any members that were specified in the member spec but have not been discovered by this group will not be included.

Returns:
the number of realised members of this group.

visit

public void visit(GroupVisitor visitor)
Visits this group. This method does not automatically traverse the children of the group, to do this the visitor can call visitMembers(GroupVisitor).

Parameters:
visitor - the visitior.

visitMembers

public void visitMembers(GroupVisitor visitor)
Visits just the members of this group.

Parameters:
visitor - the visitor.

getBuilder

public GroupBuilder getBuilder()
Gets the current builder for this group. This method will continue to return the same builder instance until GroupBuilder.applyChanges() or GroupBuilder.discard() is called.

Returns:
the current group builder.

getExpansionPointBuilder

public ExpansionPointBuilder getExpansionPointBuilder()
Gets the current expansion point builder for this group. This method will continue to return the same builder instance until ExpansionPointBuilder.applyChanges() or ExpansionPointBuilder.discard() is called.

Returns:
the current expansion point builder.

getMemberManager

protected MemberManager getMemberManager()
Gets the member support for this group. This method lazily creates the manager.

Returns:
the member support for this group.

createMemberManager

protected MemberManager createMemberManager()
Creates the member manager. This method exists for unit testing.

Returns:
the new member manager.

memberIterator

public java.util.Iterator<GroupMember> memberIterator()
Returns an iterator over this groups GroupMember instances. This method is used for internal group management and generally should not be used.

Returns:
an iterator over this groups GroupMember instances.

addGroupListener

public void addGroupListener(GroupListener l)
Adds a GroupListener to the group.

Parameters:
l - the listener to installFace.

removeGroupListener

public void removeGroupListener(GroupListener l)
Removes a GroupListener from the group.

Parameters:
l - the listener to remove.

isAllowableMember

public boolean isAllowableMember(Command prospectiveMember)
Checks if the specified Command can be added to this group. By default this method returns true but can be overriden by subclasses to control the command types that are allowable.

Parameters:
prospectiveMember - the command that is to be added to the group.
Returns:
true if the command type is allowable for this group, false otherwise.
See Also:
ToggleGroup.isAllowableMember(com.pietschy.command.Command)


Copyright © 2006 - 2007 Andrew Pietsch