| # GUI Commands User Guide ## Version 2.1 |
| # 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: The group will be created and bound to the container of the first group to request it. 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. |