Each XmlUi client should have a single XML file which descibes how its actions are laid out in the tool strip and menus.
xmlui | The root element. May contain zero or more strip and zero or more menu elements. |
strip | Element representing the tool strip. Must have an id attribute. May contain one or more section elements or one or more action elements (in that case a small strip without sections is created). |
section | Element representing a section of a tool strip. Must have an id attribute. May contain one or more action and/or grid elements. |
grid | Element representing a grid of actions laid out in two rows. May have an id attribute. May contain one or more action and/or row elements. |
row | Element representing a row of small actions without text in a grid. May have an id attribute. May contain one or more action and/or row elements. |
menu | Element representing a popup menu or context menu. Must have an id attribute. May contains zero or more action, separator and menu elements. Menus can be nested to any depth. |
action | Element representing an action in a menu or tool strip. Must have an id attribute. |
separator | Element representing a spearator in a menu. |
For example, this is a part of the XML file associated with the text view of the demo application:
<xmlui> <strip id="stripMain"> <section id="sectionFile"> <action id="popupSaveFile"/> </section>
</strip> <menu id="menuSaveFile"> <action id="saveFile"/> <action id="saveFileAs"/> </menu>
</xmlui>
When multiple clients are added to a UI builder, their layout of menus and tool strips is merged into a single tree. Merging is performed in the same order as the clients were added, i.e. the second client's layout is merged into the first client's layout, then the third client's layout is merged into the result, and so on. In other words, the first client determines the general layout and the actions of the remaining clients are 'plugged' into appropriate places.
When merging two clients, if an element is already defined by the previous client, its location is not modified and the child elements are recursively merged with the original element. Otherwise, the element is appended to the parent element. Elements are compared by identifiers. Elements without identifiers (for example separators) are never merged.
By default, elements defined by the merged client are appended after the ones from the previous clients. To define a different location where merged elements should be inserted, use an empty merge element. For example, a default location where sections should be merged into a toolstrip can be specified this way.
Note that multiple occurences of separators are 'collapsed' into a single one, and separators appearing at the begining or end of the menu are removed. So you can use separators before and after merge locations and they will be removed if no visible actions are actually merged.
Empty menus, sections and other layout elements are not created. This can be used to define placeholders which will be created when other clients add actions to them. An element is considered empty when it contains no visible action. Because of that, if you change the visible attribute of some action after the UI way created, you may need to force updating the UI by calling the rebuildAll method.
It is also possible to create placeholders for actions, because actions which are not found in any of the clients are simply ignored. This allows to define the location of frequently used actions in the top level XML file. For example, the 'Cut', 'Copy' and 'Paste' items could be placed in the main window's toolstrip and only items for actions which are defined in the current view would be created.
When looking for an action, all clients are searched in reverse order, i.e. from the last added to the first added. This allows, for example, to override an existing action in a plug-in. When the plug-in is added to the window's builder, its action would replace the original action with the same identifier. The same rule applies when looking for the section titles.
In case of complex applications, defining a single location where actions are merged is not enough. For example, in an advanced text editor, some actions could be inserted into the 'Edit' menu after the 'Paste' item, some after the 'Find' item, and some at the end of the menu. In such cases groups can be used.
A group can be created using a group element. It must contain the id attribute which identifies matching groups during the merge operation. A group element can be placed on any level of the hierarchy and may contain any elements which are allowed on its parent's level, including nested groups.
Groups are merged using the same rules as for other elements. If two clients contain the same group, the elements from the second group are appended to the elements of the first one, unless a merge element is present which specifies a different merge location.
When all clients are merged into a single hierarchy of elements, all group elements are 'flattened', i.e. replaced by their children. So effectively groups have no meaning for the structure of the UI, they only influence the order in which elements are merged.
1.7.1