Groups allow commands to be grouped together and act as factories for menus, toolbars and the like.  Some of the features of groups are:

• They allow the grouping of both commands and other groups
• Child groups can be specified as inline.  Inlining a group causes its children to be included directly into the parent.
• The expansion point for the group can be specified by the user and allows control over the placement of separators.
• Groups listen to the registration of new commands and update their attachments automatically.
• Groups have faces just like commands.
• Groups can contain ToggleCommands that are rendered as radio buttons.  This feature is discussed on the ToggleCommands page.

The following is an example of a group definition.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE commands SYSTEM "commands.dtd">
<commands version="1.1.0">
   <group id="my.first.group">
      <face>
         <text>My _Group</text>
         <icon type="classpath">images/my-group-icon.gif</icon>
      </face>
      <members>  
         <member command-id="my.command"/>
         <separator/>
         <member command-id="my.second.group" inline="true"/>
         <expansion-point separator="before"/>
      </members>  
   </group>
</commands>

Groups are different from commands in that they don't require explicit creation. This is because the generally don't contain any user defined behavior and the default implementation provides all that is required. You can of course customize the behavior of groups, but that's another subject.

It is worth noting two points:

1. Commands must be exported to become available to groups.
2. Groups can be created before the members they contain. This is because they listen for 'new exports'.

For example.

// create a group that contains MyCommand (XML defines MyCommand as a member)
CommandGroup myGroup = CommandManager.defaultInstance().getGroup("my.first.group");

// create the command and export it
MyCommand myCommand = new MyCommand();
myCommand.export();

When the command is exported, all groups that are contain it will be notified. At this point they will update their menus and toolbars etc with the new command.

Inline Groups

The example above shows one of the group members as being and "inline" member. Normally when one group is added to another, it's as a nested element, a submenu for example. However, when a child group is added 'inline', the nesting is removed its members are added directly into the parent. To the end user it appears that the two groups have been merged into one. This is particularly useful when dealing with toggle commands.

Expansion Points

Expansion points define the point at which programatically added members will be inserted. These are particularly usefull when plugins can programatically add members to existing groups. It's possible to specifiy that separators be placed before, after or both before and after the expansion point. The separators will only be rendered if the expansion point contains at least one visible member.

At any point the expansion points of a group can be emptied by calling the groups reset method.