The ability to include layout specifications in a Dialog resource in a .r file has been added. "Layout Resource Definitions" and "Layout Items" have been added that correspond with the 5 "Layout Types". In addition, special-purpose layout items have been added, such as EndLayout, GridRow / EndRow, Spacing and Stretch.
The "Layout Resource Definitions" can be used to establish standard margins and spacing. Each of the 5 layout types has an associated resource struct that can be used to define a layout resource definition with an ID that can be referenced from a "Layout Item", described below. The layout resource structs are defined in <Mstn\MdlApi\dlogbox.r.h>. They include:
Other supporting resource structs defined in <Mstn\MdlApi\dlogbox.r.h> include:
There are a number of predefined Layout Resource Definitions defined in MicroStation and built into ustation.rsc. These should be used for Bentley layout standardization. You may define your own with unique margins and spacing, but do so after considering the standard layouts.
As a sample of a standard Layout Resource Definition, consider the following :
This layout, which has an ID of HSTACKLAYOUTID_DialogButtons, can be used when defining the layout of OK and Cancel buttons at the bottom of a modal dialog. This Horizontal StackLayout establishes left, top, right and bottom margins to use around the layout contents, and also sets the spacing to be inserted between the buttons. XC_3_2 is defined in dlogbox.r.h as "(XC*3/2)", which is roughly 9 dialog coordinates.
This next GridLayoutRsc sample, with an ID of GRIDLAYOUTID_3ColsToggleLabelSetting, establishes a standard 3 column layout useful for Tool Settings with a "Toggle Label: SettingsItem " formatting. The 4th column establishes a Stretch Factor at the end of the Grid row to prevent row stretching.
This FlowLayoutRsc sample, with an ID of FLOWLAYOUTID_IconButtons, establishes a standard layout for Icon Buttons that are usually at the top of a dialog. The FlowLayout will wrap its button onto a new row when there is not enough room on the first row for all buttons. The margins and spacing are just a single dialog coordinate.
The "Layout Items" can be used in the Dialog Item List of a DialogBoxRsc, DialogItemListRsc, CmdItemList (Tool Settings) or DItem_TabPageRsc. The "Begin" layout item types begin, or start, a layout and form a virtual hierarchy in the item list. The EndLayout ends the "Begin" layout item immediately preceding it.
Layout helper macros are provided for each Layout Item and should be used in .r files instead of full item list specifications.
The Layout Resource Definition IDs specified in the Begin* layout items and macros reference a defined layout resource that specifies margins for the layout itself and spacing within the layout. However, the resource definitions are optional. When not referencing a Layout Resource Definition, the ID value should be 0. See the LayoutResourceDefinition.
Many of the items and macros below take an auxInfo argument. The auxInfo values set overrides for certain layout properties. See ExtendedIntAttributesandOverrides.
| Layout | Macro | Description |
|---|---|---|
| GridLayout | BEGIN_GRID_LAYOUT(id,auxinfo) | Begins a GridLayout. Rows may be defined using the GridRow and EndRow items. If not using GridRow, items and layouts within this layout should specify a Row using EXTINTATTR_ROW or the row= auxInfo override. Columns within a Row are automatically assigned when using GridRow; each item in the GridRow is assigned a column number sequentially starting with 0. To override the automatic column assignment or when not using GridRow, items and layouts within this layout can specify a Column using EXTINTATTR_COLUMN or the column= auxInfo override. colSpan and rowSpan are optional properties. The colSpan property specifies the number of columns a cell should span. The rowSpan property specifies the number of rows a cell should span. |
| FlowLayout | BEGIN_FLOW_LAYOUT(id,auxinfo) | Begins a FlowLayout. Horizontal and vertical spacing may be specified. |
| HStackLayout | BEGIN_HSTACK_LAYOUT(id,auxinfo) | Begins a horizontal StackLayout. Horizontal spacing may be specified. |
| vstacklayout | BEGIN_HSTACK_LAYOUT(id,auxinfo) | Begins a horizontal StackLayout. Horizontal spacing may be specified. |
| HSplitterLayout | BEGIN_HSPLITTER_LAYOUT(id,auxinfo) | Begins a horizontal SplitterLayout. A Sash item should be placed between two items or layouts. |
| VSplitterLayout | BEGIN_VSPLITTER_LAYOUT(id,auxinfo) | Begins a vertical SplitterLayout. A Sash item should be placed between two items or layouts. |
| DockLayout | BEGIN_DOCK_LAYOUT(id,auxinfo) | Begins a DockLayout. Items and layouts within this layout should specify a DockPosition using EXTINTATTR_DOCK_POSITION or the dockPosition= auxInfo override. |
| ENDLayout | END_LAYOUT | Ends the preceding "Begin" layout item. |
| GridRow | GRID_ROW(stretch,auxinfo) | Begins a GridLayout row. The row number is incremented. Items following the GridRow item use the current row number. When using GridRow, the 'row' property is not required on each item or layout within the GridLayout. Columns within a Row are automatically assigned sequentially if not overridden. A stretch value can be specified in the 'itemArg' field in the DialogItemRsc. See StretchFactor. |
| EndRow | END_ROW | Ends the preceding GridRow. |
| Spacing | SPACING(amount) | Adds some space between two items in the current FlowLayout or StackLayout. The value in the 'width' field in the DialogItemRsc is used as the amount of space. |
| Stretch | STRETCH(amount) | Adds a stretchable space with a stretch factor and zero minimum size to the current StackLayout. The value in the 'itemArg' field in the DialogItemRsc is used as the stretch factor for the stretchable space. Placing a Stretch of 1 to a StackLayout before items with a Stretch factor of 0, which is the default, will effectively push those items to the end of the StackLayout. This is useful for putting Push Buttons in the lower right hand corner. See StretchFactor. |
| AUTO_XY | Defined as 0, 0. Convenience macro for the DialogItemRsc sextant x,y fields to indicate the Layout Manager will determine position | |
| AUTO_XYWH | Defined as { 0, 0, 0, 0}. Convenience macro for the DialogItemRsc sextant field to indicate the Layout Manager will determine position and default size | |
| NO_ITEMARGS | Defined as ON, 0, " ", " ". Convenience macro for the DialogItemRsc attributes, itemArg, label and auxInfo fields |
Each dialog item has its own set of layout properties. The RawItemHdr struct defined in <Mstn\MdlApi\dlogitem.h> has a 'layoutPropertiesP' member that points to a GuiLayoutProperties struct, which is defined in <Mstn\MdlApi\GuiLayoutProperties.h>. GuiLayoutProperties contains layout properties that are populated during item creation and when parsing the dialog item list.
GuiLayoutProperties contains the following layout properties. There is a getter and setter for each.
The final value of a property for an item is determined by this order of processing:
Layout properties for dialog items may be specified using extendedIntAttributes on the item definition or overrides in the 'auxInfo' field of the DialogItemRsc entry. The EXTINTATTR #defines for the layout properties are defined in <Mstn\MdlApi\dlogbox.r.h>. The following table lists the layout attributes and their 'auxInfo' field overrides. Note that values in the auxInfo field may be surrounded by single-quotes(') or double-quotes("). Override key='value' pairs are separated by a comma.
| extendedIntAttribute | Description | auxInfo Override |
|---|---|---|
| EXTINTATTR_MARGIN | Margin for left, top, right & bottom when in a layout. The default is 0. The units specified are in dialog coordinates. | margin='l,t,r,b' (see marginOverride) |
| EXTINTATTR_MARGIN_LEFT | Left margin when in a layout | margin= or marginLeft= |
| EXTINTATTR_MARGIN_TOP | Top margin when in a layout | margin= or marginTop= |
| EXTINTATTR_MARGIN_RIGHT | Right margin when in a layout | margin= or marginRight= |
| EXTINTATTR_MARGIN_BOTTOM | Bottom margin when in a layout | margin= or marginBottom= |
| EXTINTATTR_SPACING | Spacing for a Layout. The units specified are in dialog coordinates. | spacing= |
| EXTINTATTR_STRETCH | Stretch for an item or layout | stretch= (See StretchFactor) |
| EXTINTATTR_DOCK_POSITION | Dock Position in a DockLayout; valid values come from the DockPosition enum. | dockPosition= ; valid values are: 'left', 'top', 'right', 'bottom', 'fill' |
| EXTINTATTR_COLUMN | Column in a GridLayout. This overrides the default: when inside a GridRow, the column is automatically assigned sequentially starting with 0; when not using GridRow, the default is 0. | column= |
| EXTINTATTR_COLSPAN | Column Span in a GridLayout. The default is 1. A value of -1 is the same as the 'Star' value. | colSpan= (see colSpanOverride) |
| EXTINTATTR_ROW | Row in a GridLayout. The default is 0. | row= |
| EXTINTATTR_ROWSPAN | Row Span in a GridLayout. The default is 1. | rowSpan= |
| EXTINTATTR_HORIZONTAL_ALIGNMENT | Horizontal Alignment in a GridLayout or StackLayout; valid values come from the HorizontalAlignment enum. The default is 'stretch'. | horizontalAlignment= ; valid values are: 'left', 'right', 'center', 'stretch' (see HorizontalAlignment) |
| EXTINTATTR_VERTICAL_ALIGNMENT | Vertical Alignment in a GridLayout or StackLayout; valid values come from the VerticalAlignment enum. The default is 'stretch'. | verticalAlignment= ; valid values are: 'top', 'bottom', 'center', 'stretch' (see VerticalAlignment) |
| EXTINTATTR_HORIZONTAL_SIZEPOLICY | Horizontal Size Policy; valid values come from the SizePolicyType enum | sizePolicy= (see sizePolicyOverride) |
| EXTINTATTR_VERTICAL_SIZEPOLICY | Vertical Size Policy; valid values come from the SizePolicyType enum | sizePolicy= (see sizePolicyOverride) |
| EXTINTATTR_MINWIDTH | Minimum Width when in a layout. The units specified are in dialog coordinates. | minWidth= |
| EXTINTATTR_MINHEIGHT | Minimum Height when in a layout. The units specified are in dialog coordinates. | minHeight= |
| EXTINTATTR_MAXWIDTH | Maximum Width when in a layout. The units specified are in dialog coordinates. | maxWidth= |
| EXTINTATTR_MAXHEIGHT | Maximum Height when in a layout. The units specified are in dialog coordinates. | maxHeight= |
The margin= override value can have one, two or four numbers. A single number applies to all sides. When two numbers are used, the first applies to the left and right, and the second applies to the top and bottom. When four numbers are used, they apply to the left, top, right and bottom, respectively. The units specified are in dialog coordinates.
The sizePolicy= override value can have one or two entries. A single entry applies to both horizontal and vertical size policies. When two entries are used, they apply to the horizontal and vertical size policies, respectively. Valid entries are: 'Fixed', 'Minimum', 'Maximum', 'Preferred', 'Expanding', 'MinimumExpanding', 'Ignored'. An explanation of the values can be found above and in LayoutEnums.r.h. The "desired" value comes from the width and height specification in the item list.
The colSpan= override can either have a numeric value or a value of '*', AKA the Star value. The Star value indicates the column should span from the specified column, via column='n', to the end of the row. The Star value is only valid if the enclosing GridLayout has an associated GridLayoutRsc containing column information. Internally, the Star value is -1.
The HorizontalAlignment property declares the horizontal alignment characteristics to apply to items. The following table shows each of the possible values of the HorizontalAlignment property.
| Member | Description |
|---|---|
| Left | Items are aligned to the left of the parent layout's allocated layout space. |
| Center | Items are aligned to the center of the parent layout's allocated layout space. |
| Right | Items are aligned to the right of the parent layout's allocated layout space. |
| Stretch (Default) | Items are stretched to fill the parent layout's allocated layout space. |
The VerticalAlignment property describes the vertical alignment characteristics to apply to items. The following table shows each of the possible values for the VerticalAlignment property.
| Member | Description |
|---|---|
| Left | Items are aligned to the top of the parent layout's allocated layout space. |
| Center | Items are aligned to the center of the parent layout's allocated layout space. |
| Right | Items are aligned to the bottom of the parent layout's allocated layout space. |
| Stretch (Default) | Items are stretched to fill the parent element's allocated layout space. |
Several MDL dialog items allow a label to be part of the item, and the label can be displayed to the left, right or above the item. This has always seemed like a nice feature. Unfortunately, it causes certain problems for the Layout Manager because the sizes of the label and associated item need to be treated separately, especially when each needs to be in a different GridLayout column. To compensate for this dilemma, a couple of attributes have been added for the Label item: LABEL_LINKPREV and LABEL_LINKNEXT.
When a dialog item and its associated Label need to be in separate GridLayout columns, a Label item should be added to the dialog item list above or below the associated item. However, instead of assigning the actual label string to the Label item, the label string is kept with the associated item in case the item needs to be used outside a layout. The Label item specifies either the LABEL_LINKPREV or LABEL_LINKNEXT itemArg value in order to link to the previous or next item. This pulls the label string from the associated item over to the Label item and links the two items for focus processing. This allows the label and associated item to specify different columns, size policies and alignment for layout purposes.
The LABEL_WORDWRAP attribute has existed for years and supports '
' line breaks and wrapping at word breaks. But support for LABEL_WORDWRAP has been expanded when a Label item is in a layout. As the label width gets narrower when the user resizes the dialog, the label will wrap at word breaks and the height of the label will increase. The items below the Label will automatically be repositioned to compensate. The width specified for the Label in the DialogItemRsc is the "desired" width, so it is important to apply a MinWidth property to the Label in this case.