GUI Commands User GuideVersion 2.1 |
||
Expansion PointsExpansion points define growth points for groups at runtime. A typical example would be a plugin that provides its own menu, or one that adds additional content to an existing menu. Expansion points ensure the new content is inserted at the correct point. The expansion point location is defined by the The following is an example of specifying an expansion point that places a separator before its content:
group!file-menu@members=\
new, \
open, \
save, \
save-as, \
expand(separatorBefore), \
separator, \
exit
The content of expansion points is managed using
CommandGroup group = new CommandGroup("file-menu");
// get the builder
ExpansionPointBuilder builder = group.getExpansionPointBuilder();
// remove any existing members from the expansion point.
builder.clear();
// add a command.
builder.add(anotherCommand);
builder.addSeparator();
// and an inline group.
builder.addInline(anotherGroup);
// apply the changes
builder.applyChanges();
Unlike Group Builders expansion point builders only let you add actual command instances. You can't add commands or groups using just the command Id. EmbeddingExpansion point builders allow you to embed new members within an existing group structure. Embedded groups are automatically added inline to existing group members that have matching text. If no match is found the group is added normally to the main group's expansion point. ExampleThe following is the main menu definition from the online demo.
group!main-menu@members=\
file-menu, \
view-menu, \
edit-menu, \
download-menu, \
expand, \
help-menu
group!help-menu@face.text=_Help
group!help-menu@members=help-about, expand(separatorBefore)
This produces the standard menu as shown below:
Standard Menu
Each example withing the demo can provide one or more contributions for the main menu. The face
example provides two menus,
group!face.menu@face.text=Face Menu
group!face.menu@members=\
face.basic-command,\
face.text-leading,\
face.text-bottom,\
face.icon-factory-example,\
face.rollover-example,\
face.selected-icon-example,\
face.disabled-icon-example,\
face.client-property-example
group!face.help-menu@face.text=_Help
group!face.help-menu@members=face.help-about
When ever you select a new example, the main frame retrieves its menu contributions and embedds them into the main menu. This is achieved as follows: CommandGroup mainMenuGroup = ...; // get the builder ExpansionPointBuilder builder = mainMenuGroup.getExpansionPointBuilder(); // clear any previous contributions from the menu, returning // it to its original state builder.clear(); // Now add all the contributions. The face demo returns the // The following shows the before and after menu structure after selecting the face examples: Before:
After:
Notice how Using Custom ComparatorsThe builder also supports embedding using an arbitrary Comparator if you'd prefer no to match based on the text properties of the groups. The following is an example.
ExpansionPointBuilder builder = group.getExpansionPointBuilder();
// use a custom comparator when embedding groups.
builder.addEmbedded(contribution, new CustomComparator());
builder.applyChanges();
|
||