Automatic Creation

Normally command groups are only created when you explicitly call new CommandGroup(..). This can be inconvenient when creating a nested menu structure such as a main menu bar. In this case you only want to create the top level group and have the children automatically created for you. To achieve this you can set the autoCreate property of the child groups to true.

The following example shows a main menu bar group and its children. Each child is specified to be automatically created when the main menu group is built:

   group!main-menu@members=file-menu, edit-menu, help-menu

   group!file-menu@face.text=_File
   group!file-menu@autoCreate=true
   group!file-menu@members=...

   group!edit-menu@face.text=_Edit
   group!edit-menu@autoCreate=true
   group!edit-menu@members=...

   group!help-menu@face.text=_Help
   group!help-menu@autoCreate=true
   group!edit-help@members=... 

To create this menu all we need to do is the following:

   // All our children are marked as autoCreate so
   // we only need to create the parent group.
   CommandGroup mainMenu = new CommandGroup("main-menu");
   mainMenu.bind(...);

If we had not specified autoCreate then we would need to programmatically create each of the child groups as follows:

   // Create the main group.
   CommandGroup mainMenu = new CommandGroup("main-menu");
   mainMenu.bind(...);

   // if autoCreate=false then we'd need to manually
   // create all the children as follows
   new CommandGroup("file-menu").bind(...);
   new CommandGroup("edit-menu").bind(...);
   new CommandGroup("help-menu").bind(...);   

Specifying the Class

You can control the class instantiated by setting the class property of the group. If left unspecified a standard CommandGroup will be created. The following example shows specifying a custom class for automatically created groups:

   group!file-menu@face.text=_File
   group!file-menu@autoCreate=true
   group!file-menu@class=my.package.CustomGroup

Auto Create Gotcha's

When automatically creating groups there are some issues to be aware of:

  1. The group will be created and bound to the container of the first group to request it.
  2. If you have a container hierarchy you could end up with multiple instances of the group.

Mulitple instances of the same group can be troublesome if you need to perform any programmatic modifications. In this case, only one instance will update and you'll end up confused. In general you should avoid using autoCreate for groups that are accessed programmatically.

When using autoCreate you can avoid multiple group instances by ensuring:

  • The highest level container is the first to request the group. E.g. in the example above I would ensure that the main menu group is created and bound to the top level container before anything else.
  • Child containers are parented before groups are bound to them. That way the child container can find previously created groups in the parent and won't create its own instance.

If you're unsure it's best to leave autoCreate undefined or false and programmatically create the group.