Dialog Resource Integration

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.

Layout Resource Definitions

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:

Standard Layout Resource Definitions

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 :

// Convenience macros for common layouts
#define XC_3_2 (XC*3/2)
#define MAIN_MARGIN XC_3_2
#define BUTTON_HSPACING XC_3_2
// Used for OK/Cancel buttons at the bottom of a dialog
{
{MAIN_MARGIN, MAIN_MARGIN, MAIN_MARGIN, MAIN_MARGIN}, // Margins - Left, Top, Right, Bottom
BUTTON_HSPACING // Horizontal Spacing
};

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.

#define XC_3_2 (XC*3/2)
#define MAIN_MARGIN XC_3_2
#define ROW_SPACING YC/3
#define GRID_HSPACING XC
#define GRID_VSPACING ROW_SPACING
// Used for "Toggle Label: SettingsItem" formatting. Has a stretch at the end to prevent row stretching.
GridLayoutRsc GRIDLAYOUTID_3ColsToggleLabelSetting =
{
{MAIN_MARGIN, MAIN_MARGIN, MAIN_MARGIN, MAIN_MARGIN}, // Margins - Left, Top, Right, Bottom
GRID_HSPACING, GRID_VSPACING, // HSpacing, VSpacing
{ // Column Definitions
{0, "toggleColumn3"}, // Stretch, SharedSizeGroup
{0, "labelColumn3"},
{0, "settingColumn3"},
{1, "stretchColumn3"}, // Extra column with a Stretch Factor of 1
} // to prevent unwanted row expansion
};

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.

*//* Convenience macros for common layouts in
#define FLOW_MARGIN 1
#define FLOW_HSPACING 1
#define FLOW_VSPACING 1
// Used for Icon Buttons in a FlowLayout resembling a Toolbar at the top or bottom of a dialog
{
{FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN}, // Margins - Left, Top, Right, Bottom
FLOW_HSPACING, FLOW_VSPACING // HSpacing, VSpacing
}; @code{.unparsed}
*

Layout Items

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

Dialog Item Layout Properties

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:

  1. A default is set in the GuiLayoutProperties constructor
  2. Each dialog item type may have its own default, especially in the case of the SizePolicy.
  3. An item hook or hook handler may set a value in OnInit () or when processing the DITEM_MESSAGE_INIT message.
  4. When reading the item definition, the extendedIntAttribute values are applied (See "Extended Int Attributes and Overrides" below).
  5. The 'auxInfo' field override values are applied (See "Extended Int Attributes and Overrides" below).

Extended Int Attributes and Overrides

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=
Note
All auxInfo overrides begin with a lower-case letter.
There is no Extended Attribute or Override for the Shared Size Group of a Grid Column. Shared Size Group names must be set in each GridColumnRsc of a GridLayoutRsc Layout Resource Definition. See LayoutResourceDefinition.

margin= Override

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.

sizePolicy= Override

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.

colSpan= Override

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.

HorizontalAlignment

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.

VerticalAlignment

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.

Label Items

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.

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.

LABEL_WORDWRAP

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.


Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.