The content of this page was extracted from the MicroStationAPI help document delivered with the MicroStation CONNECT SDK. You can find it in that help document by searching for BEGIN_VSTACK_LAYOUT or other keywords.
The original header file contains HTML markup tags, which the Bentley document formatter has been unable to use. We've isolated the HTML markup so you can read it more easily. Copyright remains with Bentley Systems.
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 @ref LayoutResourceDefinition.
Many of the items and macros below take an auxInfo argument. The auxInfo values set overrides for certain layout properties. See @ref 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 @ref 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 @ref 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
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
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 @ref 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 @ref 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 @ref 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 @ref 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 @ref VerticalAlignment) |
EXTINTATTR_HORIZONTAL_SIZEPOLICY | Horizontal Size Policy; valid values come from the SizePolicyType enum | sizePolicy= (see @ref sizePolicyOverride) |
EXTINTATTR_VERTICAL_SIZEPOLICY | Vertical Size Policy; valid values come from the SizePolicyType enum | sizePolicy= (see @ref 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.
* * @anchor sizePolicyOverride *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.
* * @anchor colSpanOverride *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.
* * @anchor 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. |
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 '\n' 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.
* *@addtogroup MigrationInstructions *Instructions for migrating MDL Dialogs and Tool Settings to the Layout Manager can be found in the section: @ref LayoutManagerMigration "Migrating to Layout Manager".
* *@addtogroup Examples *The following example from the "View Groups" application makes use of three layout types: VStackLayout, FlowLayout and HStackLayout. The vertical StackLayout is the outermost layout. The first nested layout is a FlowLayout for the dialog's IconCmd buttons. The FLOWLAYOUTID_IconButtons FlowLayout definition is in ustation.rsc . A ListBox is next in the vertical stack and has a stretch factor of 1 so it gets more space vertically as the dialog is resized larger. The next nested layout is a horizontal StackLayout that contains a Stretch item and two PushButtons. The Stretch item is given a stretch factor of 1 so it gets more space horizontally as the dialog is resized larger. The HSTACKLAYOUTID_DialogButtons HStackLayout definition is also in ustation.rsc . For standardization of margins and spacing, layouts defined in MicroStation should be used when possible.
* * @code{.unparsed} DialogBoxRsc DIALOGID_VIEWGROUP_ViewGroups = { DIALOGATTR_DEFAULT | DIALOGATTR_SINKABLE | DIALOGATTR_GROWABLE, DIALOG_LIST_W, DIALOG_H, NOHELP, MHELPTOPIC, HOOKDIALOGID_VIEWGROUP_ViewGroups, NOPARENTID, TXT_ViewGroupDialogTitle, { BEGIN_VSTACK_LAYOUT(0, "") BEGIN_FLOW_LAYOUT (FLOWLAYOUTID_IconButtons, "") {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Create, NO_ITEMARGS}, {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Properties, NO_ITEMARGS}, {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Delete, NO_ITEMARGS}, END_LAYOUT {{ AUTO_XY, VIEWGROUP_LIST_WIDTH, 0}, ListBox, LISTID_VIEWGROUP_ViewGroups, NO_ITEMARGS}, BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "") STRETCH(1) {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Apply, NO_ITEMARGS}, {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Close, NO_ITEMARGS}, END_LAYOUT END_LAYOUT } }; * @endcode * *The following example from the "Place Line" command is placing two rows in a GridLayout. The items on the row are surrounded by the GridRow and EndRow items. Each item is automatically assigned a sequential column number. Each row contains a ToggleButton, Label and Text field. The ToggleButton actually contains the label string. But for layout purposes, a Label item is added and specifies the "LABEL_LINKPREV" itemArg value in order to link to the previous item (the ToggleButton). Using this technique, the label string is pulled over to the Label item and the two items are "linked" for the focus model. This allows the ToggleButton to keep the label in its resource definition in case it is used outside a layout, and also allows the Label item to "link" to it and specify an independent column and size policy for layout purposes. In this case, the default "left alignment" is applied to the Label item. The "LABEL_LINKNEXT" itemArg value would pull the label string from the following item.
* * @code{.unparsed} * #define W10 10*XC CmdItemListRsc CMD_PLACE_LINE_CONSTRAINED = {{ BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "") GRID_ROW(0, "") // row 0 {{0, 0, 0, 0}, ToggleButton, TOGGLEID_Length, ON, 0, "", ""}, // column 0 {{0, 0, W10, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""}, // column 1 {{0, 0, W10, 0}, Text, TEXTID_Length, ON, 0, "", ""}, // column 2 END_ROW GRID_ROW(0, "") // row 1 {{0, 0, 0, 0}, ToggleButton, TOGGLEID_Angle, ON, 0, "", ""}, {{0, 0, W10, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""}, {{0, 0, W10, 0}, Text, TEXTID_Angle, ON, 0, "", ""}, END_ROW END_LAYOUT }}; * * @endcode * *The following example is an excerpt from the Configuration Variables dialog application. The CfgVars dialog was a fixed size in V8i. By creating and setting up the GuiLayoutHelper and adding all the dialog items to various nested layouts, we were quickly and easily able to improve the layout of the dialog and make it resizable.
* * @code {.unparsed} * virtual bool OnInit (DialogInitArgsR init) override { // Create the GuiLayoutHelper that will hold the top-level layout GuiLayoutHelper *layoutHelper = GuiLayoutHelper::Create (GetDbP()); // Create a vertical Stack layout, which is the top-level layout VStackLayout *vStackLayout = VStackLayout::Create(); vStackLayout->SetContentsMargins (0); // Get the MenuBar on the dialog and add it to the vertical Stack layout DialogItem *diP = GetDbP()->GetItemByTypeAndId (RTYPE_MenuBar, MENUBARID_CfgVars); if (NULL != diP) vStackLayout->AddControl (GuiLayoutControl::Create(layoutHelper, diP, SizePolicy(ST_Preferred, ST_Fixed))); // Create a horizontal stack layout, which will hold a ListBox on the left // and a ContainerPanel to the right of it. HStackLayout *hStackLayout1 = HStackLayout::Create (); hStackLayout1->AddSpacing (XC); diP = GetDbP()->GetItemByTypeAndId (RTYPE_ListBox, LISTBOXID_ConfigurationTopicList); if (NULL != diP) hStackLayout1->AddControl (GuiLayoutControl::Create(layoutHelper, diP, SizePolicy(ST_Fixed, ST_Preferred))); . . . // Add the horizontal stack layout to the top-level vertical stack layout vStackLayout->AddLayout (hStackLayout1); . . . // Set the vertical stack layout as the top-level layout layoutHelper->SetLayout (vStackLayout); // Set the GuiLayoutHelper as the layout helper for the dialog. // When the dialog size changes or control sizes/properties change, // the layout manager will automatically be invoked. GetDbP()->SetLayoutHelper (layoutHelper); return true; } * *@endcode * *@addtogroup DefaultSizePoliciesforDialogItems *The following table lists the default Size Policies for the different dialog item types. If the Size Policy needs to be changed for a dialog item, use the EXTINTATTR_HORIZONTAL_SIZEPOLICY or EXTINTATTR_VERTICAL_SIZEPOLICY extended attributes, or the "sizePolicy=" auxInfo override, which are all described @ref DialogResourceIntegration. Consider using a Stretch Factor or Stretch Item before overriding the default Size Policy of an item.
* *Dialog Item Type | Default Horizontal Size Policy | Default Vertical Size Policy |
---|---|---|
ButtonGroup | Fixed | Fixed |
Container | Preferred | Preferred |
ContainerPanel | Preferred | Preferred |
ColorChooser | Fixed | Fixed |
ColorPicker | Minimum | Fixed |
ComboBox | Minimum | Fixed |
CompactSlider | Fixed | Fixed |
FlowDocumentScrollViewer | Preferred | Preferred |
Generic | Fixed | Fixed |
GroupBox | Preferred | Preferred |
IconCmd | Fixed | Fixed |
IconPopup | Minimum | Fixed |
Label | MinimumExpanding | Fixed |
Label (with LABEL_WORDWRAP) | Preferred | Preferred |
LevelList | Preferred | Preferred |
ListBox | Preferred | Preferred |
MenuBar | Preferred | Fixed |
MultilineText | MinimumExpanding | MinimumExpanding |
OptionButton | Minimum | Fixed |
PushButton | Minimum | Fixed |
RadioButton | Minimum | Fixed |
Sash (vertical) | Fixed | Expanding |
Sash (horizontal) | Expanding | Fixed |
Scale (vertical) | Fixed | Expanding |
Scale (horizontal) | Expanding | Fixed |
ScrollBar (vertical) | Fixed | Expanding |
ScrollBar (horizontal) | Expanding | Fixed |
Separator (vertical) | Fixed | Expanding |
Separator (horizontal) | Expanding | Fixed |
SpinBox | Minimum | Fixed |
TabPageList | Minimum | Minimum |
Text | Minimum | Fixed |
ToolBox | Fixed | Fixed |
Tree | Preferred | Preferred |
UpDownButtons | Fixed | Fixed |
WinFormsControl | Fixed | Fixed |
While developing with the Layout Manager, you may encounter certain error messages when the .r layout syntax is incorrect. These error messages will appear in the "Messages" window while running the product. There is no specific syntax checking for layout manager syntax in the resource compiler. Below is a list of these error messages, along with the instructions for resolving the issue.
* *Error Message | Problem Resolution Instructions |
---|---|
Parent item for layout instructions is unknown | Layout resource items are only valid in a DialogBoxRsc, DialogItemListRsc or CmdItemListRsc. |
No previous layout item found to add this child layout to | The layout interpreter encountered a "child" layout but a parent layout was not found. Make sure each "Begin Layout" is properly paired with an "End Layout". |
Item cannot be outside a layout item | A dialog item was encountered outside a "Begin" and "End" layout block. Once a Dialog is using the Layout Manager, all items must be in a layout. PopupMenu items are the only exception to this rule. |
The grid row number is invalid. Using 0. | The current row number is less than 0. The default row is 0. Make sure the row='n' syntax is correct or that the GridRow and EndRow items are paired correctly. |
The grid column number is invalid. Using 0. | The current column number is less than 0. The default column is 0. Make sure the column='n' syntax is correct. |
Encountered a GridRow outside a GridLayout | The GridRow item may only be located inside a GridLayout / EndLayout block. |
Encountered an EndLayout without a matching "Begin" layout item | The EndLayout item must be matched with a "Begin" layout item. Make sure each "Begin Layout" is properly paired with an "End Layout". |
Spacing item cannot be used in this layout | The Spacing item is only supported in a FlowLayout or StackLayout. |
Stretch item cannot be used in this layout | The Stretch item is only supported in a StackLayout. |
The dialog has no active Layout Manager. Check the layout syntax for the dialog. | Either layout syntax was encountered for the dialog or the C++ API was used to set the GuiLayoutHelper for the dialog. But there is no LayoutManager associated with the dialog. Make sure each "Begin Layout" is properly paired with an "End Layout". |
Invalid DockPosition encountered. Valid values are DOCK_TOP, DOCK_BOTTOM, DOCK_LEFT, DOCK_RIGHT and DOCK_FILL. | EXTINTATTR_DOCK_POSITION and SetDockPosition () only accepts the Top, Bottom, Left, Right and Fill values. |
Invalid margin= value encountered. The value should have one, two or four entries. | See an explanation of the margin= syntax in the @ref marginOverride. |
Invalid integer value override encountered. | Several auxInfo override values should be integer values only. Make sure there are no alpha characters included. |
Invalid dockPosition= value encountered. Valid values are 'top', 'bottom', 'left', 'right' and 'fill'. | The dockPosition= auxInfo override value only accepts the Top, Bottom, Left, Right and Fill values. |
Invalid sizePolicy= value encountered. Valid values are 'minimum', 'maximum', 'preferred', 'minimumexpanding', 'expanding' and 'ignored'. | See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride |
Invalid sizePolicy= value encountered. The value should have two entries for horizontal and vertical. | See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride |
Invalid horizontalAlignment= value encountered. Valid values are 'left', 'center', 'right' and 'stretch'. | See an explanation of the horizontalAlignment= syntax in the @ref HorizontalAlignment |
Invalid verticalAlignment= value encountered. Valid values are 'top', 'center', 'bottom' and 'stretch'. | See an explanation of the verticalAlignment= syntax in the @ref VerticalAlignment |
The 'Star' syntax for colSpan= cannot be used for this column because the column number is too large. | The column= value is too large for the GridLayout. Check the column= and colSpan= values and also the GridLayoutRsc definition for column information. See an explanation of the colSpan= syntax in the @ref colSpanOverride |
The 'Star' syntax for colSpan= only works if you've defined Columns in the GridLayout resource. | Make sure the specified GridLayout has an associated GridLayoutRsc definition with column information. See an explanation of the colSpan= syntax in the @ref colSpanOverride |