A Dialog Layout Manager has been added to the MDL Dialog Manager.
The Layout Manager provides a simple and powerful way of automatically arranging child items within a dialog to ensure they make good use of the available space. "Layouts" automatically position and resize items when the amount of space available for them changes, ensuring that they are consistently arranged and that the user interface as a whole remains usable. A dialog has one main top-level parent layout, and numerous child layouts can be nested to achieve the overall layout for the dialog. PowerPlatform includes a number of layout types and a set of layout management classes that are used to describe how items are laid out in an application's user interface. Layout specifications may also be included in an MDL dialog's resource definition. The inspiration for our Layout Manager came from the layout systems in WPF, Qt and Java.
There are three clear benefits to using the Dialog Layout Manager:
Standardization
Margins, spacing and sizing can be easily standardized using common layouts. There are a number of layouts defined in ustation.rsc with standard margins and spacing, and these layouts should be used when possible.
Resizable Dialogs
Making a dialog resizable is very simple using the Layout Manager. Once an existing dialog is using the Layout Manager, dialog hook code that currently performs item layout and sizing as a response to WindowMoving, Resize and Update hooks messages can mostly be removed or greatly reduced.
Localization
The Layout Manager automatically adjusts for wider labels and buttons based on label width. Aspect Ratios are no longer needed for a dialog using the Layout Manager.
There are 5 different layout types available in the MDL Layout Manager.
Lays out items in rows and columns. The GridLayout is the most capable and flexible layout. Many dialogs start with the GridLayout then nest other layouts that arrange smaller groups of items. This type of layout is also known as a "Table" layout.
Lines up items horizontally or vertically. The Vertical StackLayout can be used as the main layout, especially for Tool Settings. The Horizontal StackLayout is typically used for small sections of a larger, more complex dialog This type of layout is also called a "Box" layout.
Lines up items horizontally as space permits. When there is no longer space on a single line for all items, it wraps the remainder on subsequent lines below. This type of layout is also called a "Wrap" layout..
Puts items on either side of a Sash, or Splitter, control. The SplitterLayout can be either horizontal or vertical.
Puts items along the top, bottom, left or right edge. This type of layout is also called a "Border" layout.
When specifying the layout of a dialog, numerous layouts can be nested to achieve the overall layout for the dialog. The GridLayout, VStackLayout or DockLayout are usually used as the main layout.
There are a number of concepts related to the Layout Manager. An understanding of these concepts is important in order to achieve the best results possible.
The margin is the distance between the outermost pixels of an item or layout and the invisible bounding box of the item. The default margin is 0. Each side of an item or layout has a margin. When all four values are specified in the "margin=" value, the values are listed in this order: left, top, right & bottom.
Spacing
Spacing is the distance between items or layouts inside a layout. There is both horizontal and vertical spacing in the FlowLayout and GridLayout. Extra spacing may be added between items in a FlowLayout or StackLayout. If no value is explicitly set for a child layout, the layout's spacing is inherited from the parent layout.
If any items have stretch factors set, with a value greater than zero, they are allocated space in proportion to their stretch factor. Items are normally created without any stretch factor set (0). When they are laid out in a layout, the items are given a share of space in accordance with their Size Policy or their Minimum Desired Size, whichever is the greater. Stretch factors are used to change how much space items are given in proportion to one another. The greater the stretch factor, the more space an item is given.
Stretch Factors are very useful in a number of situations. They can be used to push buttons to the right, center content within a StackLayout, push content up from the bottom, prevent items from stretching in a Grid Row, and push items to either side of a StackLayout. The use of the Stretch Factor should especially be considered before attempting to override the Size Policy of an item.
Alignment
Within a parent layout, dialog items and child layouts have a horizontal and vertical alignment property that determines how the child items are aligned within the parent layout's allocated space.
Orientation
The Orientation of a layout determines in which direction child items and layouts are added. The StackLayout and SplitterLayout layouts can have either a horizontal or vertical orientation. A FlowLayout has a horizontal orientation but also adds rows in the vertical direction when the horizontal space is filled.
Size Policy and Desired Size
The Size Policy specifies the default horizontal and vertical layout behavior of the item. The policy determines whether the size of the item is fixed or if it can shrink or grow, and the policy helps determine the value returned by GetDesiredSize (), as described in the table below. Each MDL dialog item has a default Size Policy. Button-like items, including the PushButton, OptionButton and IconPopup, set the size policy to specify that they may stretch horizontally, but are fixed vertically. The same applies to TextBox -like input items, including the Text, ComboBox and SpinBox, and other horizontally oriented items. Items that support different directions, such as Scale and ScrollBar, specify stretching in the respective direction only. Items that can provide scroll bars, such as the MultilineText, ListBox and Tree, tend to specify that they can use additional space, and that they can make do with less than the value returned by GetDesiredSize ().
Size Policy Values
| Field | Description |
|---|---|
| Fixed | The "desired" size is the only acceptable alternative, so the item can never grow or shrink (e.g. the vertical direction of a push button). |
| Minimum | The "desired" size is minimal, and sufficient. The item can be expanded, but there is no advantage to it being larger (e.g. the horizontal direction of a push button). It cannot be smaller than the size provided by GetDesiredSize (). |
| Maximum | The "desired" size is a maximum. The item can be shrunk any amount without detriment if other items need the space (e.g. a separator line). It cannot be larger than the size provided by GetDesiredSize (). |
| Preferred | The "desired" size is best, but the item can be shrunk and still be useful. The item can be expanded, but there is no advantage to it being larger than GetDesiredSize (). (the default policy). |
| Expanding | The "desired" size is a sensible size, but the item can be shrunk and still be useful. The item can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider). |
| MinimumExpanding | The "desired" size is minimal, and sufficient. The item can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider). |
| Ignored | The "desired" size is ignored. The item will get as much space as possible. |
See the Default Size Policies for Dialog Items.
Minimum Size
The Minimum Size is the smallest dimension allowed for an item. This size is important when the Size Policy for an item specifies that the item can be shrunk to a size smaller than the "desired" size. The combination of minimum sizes for all items and layouts within a dialog determines the minimum size of the dialog.
Maximum Size
The Maximum Size is the largest dimension allowed for an item. This size is applicable when the Size Policy for an item specifies that the item can be expanded to a size larger than the "desired" size.
Shared Size Group
A SharedSizeGroup allows columns to automatically have the same size across multiple GridLayouts on a dialog. When defining the columns for a GridLayout in a GridLayoutRsc definition, a Shared Size Group name can be specified for each column. When multiple GridLayouts in a dialog contain columns that have the same Shared Size Group name, those columns will share sizing properties. The widest minimum and desired column sizes from the multiple GridLayouts will be used for each column in the group, resulting in consistent column widths across GridLayout boundaries.