Urho3D
|
Urho3D implements a simple, hierarchical user interface system based on rectangular elements. The elements provided by default are:
The root UI element can be queried from the UI subsystem. It is an empty canvas (UIElement) as large as the application window, into which other elements can be added.
Elements are added into each other similarly as scene nodes, using the AddChild() and RemoveChild() functions. Each UI element has also a user variables VariantMap for storing custom data.
User interface elements derive from Serializable, so they can be serialized to/from XML using their attributes. There are two distinct use cases for UI definition files: either defining just the UI element style and leaving the actual position and dimensions to be filled in later, or fully defining an UI element layout. The default element style definitions, used for example by the editor and the debug console, are in the file Data/UI/DefaultStyle.xml.
The function LoadLayout() in UI will take an XML file and instantiate the elements defined in it. To be valid XML, there should be one root UI element. An optional style XML file can be specified; the idea is to first read the element's style from that file, then fill in the rest from the actual layout XML file. This way the layout file can be relatively simple, as the majority of the data is already defined.
See the elements' C++ code for all supported attributes, and look at the editor's user interface layouts in the Data/UI directory for examples. The serialization format is similar to scene XML serialization, with three important differences:
1) The element type to instantiate, and the style to use for it can be set separately. For example the following element definition
tells to instantiate a Button element, and that it should use the style "CloseButton" defined in the style XML file.
2) Internal child elements, for example the scroll bars of a ScrollView, need to be marked as such to avoid instantiating them as duplicates. This is done by adding the attribute internal="true" to the XML element, and is required in both layout and style XML files. Furthermore, the elements must be listed in the order they have been added as children of the parent element (if in doubt, see the element's C++ constructor code. Omitting elements in the middle is OK.) For example:
3) The popup element shown by Menu and DropDownList is not an actual child element. In XML serialization, it is nevertheless stored as a child element, but is marked with the attribute popup="true".
Note that when UI elements are serialized back to XML using SaveLayout() it is no longer possible to separate what was defined in the style XML file, and what in the actual layout file. Instead all attributes will be serialized.
By default UI elements operate in a "free" layout mode, where child elements' positions can be specified relative to any of the parent element corners, but they are not automatically positioned or resized.
To create automatically adjusting layouts, the layout mode can be switched to either "horizontal" or "vertical". Now the child elements will be positioned left to right or top to bottom, based on the order in which they were added. They will be preferably resized to fit the parent element, taking into account their minimum and maximum sizes, but failing to do that, the parent element will be resized.
Left, top, right & bottom border widths and spacing between elements can also be specified for the layout. A grid layout is not directly supported, but it can be manually created with a horizontal layout inside a vertical layout, or vice versa.