APIIntroductionMDL.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once

/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************//* 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
 FlowLayoutRsc FLOWLAYOUTID_IconButtons =
 {
     {FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN},       // Margins - Left, Top, Right, Bottom
     FLOW_HSPACING, FLOW_VSPACING                                // HSpacing, VSpacing
 }; @code{.unparsed}
*
* @endcode
*
*<H3>Layout Items</H3>
*<P>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.</P>
*
*<P>Layout helper macros are provided for each Layout Item and should be used in .r files instead of full item list specifications.</P>
*
*<P>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.</P>
*<P> Many of the items and macros below take an auxInfo argument. The auxInfo values set overrides for certain layout properties. See @ref ExtendedIntAttributesandOverrides. </P>
*
* <table>
* <tr>
*   <th>Layout</th>
*   <th>Macro</th>
*       <th>Description</th>
* </tr>
* <tr>
*   <td>GridLayout</td>
*   <td>BEGIN_GRID_LAYOUT(id,auxinfo) </td>
*       <td>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.</td> 
* </tr>
* <tr>
*   <td>FlowLayout</td>
*   <td>BEGIN_FLOW_LAYOUT(id,auxinfo) </td>
*       <td>Begins a FlowLayout. Horizontal and vertical spacing may be specified. </td> 
* </tr>
* <tr>
*   <td>HStackLayout</td>
*   <td>BEGIN_HSTACK_LAYOUT(id,auxinfo) </td>
*       <td>Begins a horizontal StackLayout. Horizontal spacing may be specified. </td> 
* </tr>
* <tr>
*   <td>vstacklayout</td>
*   <td>BEGIN_HSTACK_LAYOUT(id,auxinfo) </td>
*       <td>Begins a horizontal StackLayout. Horizontal spacing may be specified. </td> 
* </tr>
* <tr>
*   <td>HSplitterLayout</td>
*   <td>BEGIN_HSPLITTER_LAYOUT(id,auxinfo) </td>
*       <td>Begins a horizontal SplitterLayout. A Sash item should be placed between two items or layouts. </td> 
* </tr>
* <tr>
*   <td>VSplitterLayout</td>
*   <td>BEGIN_VSPLITTER_LAYOUT(id,auxinfo) </td>
*       <td>Begins a vertical SplitterLayout. A Sash item should be placed between two items or layouts. </td> 
* </tr>
* <tr>
*   <td>DockLayout</td>
*   <td>BEGIN_DOCK_LAYOUT(id,auxinfo) </td>
*       <td>Begins a DockLayout. Items and layouts within this layout should specify a DockPosition using EXTINTATTR_DOCK_POSITION or the dockPosition= auxInfo override. </td> 
* </tr>
* <tr>
*   <td>ENDLayout</td>
*   <td>END_LAYOUT </td>
*       <td>Ends the preceding "Begin" layout item. </td> 
* </tr>
* <tr>
*   <td>GridRow</td>
*   <td>GRID_ROW(stretch,auxinfo) </td>
*       <td>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. </td> 
* </tr>
* <tr>
*   <td>EndRow</td>
*   <td>END_ROW </td>
*       <td>Ends the preceding GridRow. </td> 
* </tr>
* <tr>
*   <td>Spacing</td>
*   <td>SPACING(amount)  </td>
*       <td>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.  </td> 
* </tr>
* <tr>
*   <td>Stretch</td>
*   <td>STRETCH(amount) </td>
*       <td>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. </td> 
* </tr>
* <tr>
*   <td></td>
*   <td>AUTO_XY  </td>
*       <td>Defined as 0, 0. Convenience macro for the DialogItemRsc sextant x,y fields to indicate the Layout Manager will determine position </td> 
* </tr>
* <tr>
*   <td></td>
*   <td>AUTO_XYWH </td>
*       <td>Defined as { 0, 0, 0, 0}. Convenience macro for the DialogItemRsc sextant field to indicate the Layout Manager will determine position and default size </td> 
* </tr>
* <tr>
*   <td></td>
*   <td>NO_ITEMARGS </td>
*       <td>Defined as ON, 0, " ", " ". Convenience macro for the DialogItemRsc attributes, itemArg, label and auxInfo fields</td> 
* </tr>
*</table>
*
*<H3>Dialog Item Layout Properties</H3>
*<P>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.  </P>
*<P>GuiLayoutProperties contains the following layout properties. There is a getter and setter for each. </P>
*<UL>
*       <LI><B>Margins</B> - the distance between the outermost pixels of an item or layout and the invisible bounding box of the item.</LI>
*       <LI><B>Spacing</B> - the distance between items or layouts inside a layout.</LI>
*       <LI><B>HSpacing</B> - the distance horizontally between items or layouts inside a layout.</LI>
*       <LI><B>VSpacing</B> - the distance vertically between items or layouts inside a layout  </LI>
*       <LI><B>Stretch</B> - Stretch Factor is used to change how much space items are given in proportion to one another.</LI>
*       <LI><B>DockPosition</B> - the edge on which a DockLayout places an item.</LI>
*       <LI><B>Column</B> - the column within a GridLayout in which the item is placed.</LI>
*       <LI><B>ColSpan</B> - specifies the number of columns a cell should span</LI>
*       <LI><B>Row</B> - the row within a GridLayout in which the item is placed.</LI>
*       <LI><B>RowSpan</B> - specifies the number of rows a cell should span.</LI>
*       <LI><B>SizePolicy</B> - specifies the horizontal and vertical layout behavior of the item.</LI>
*       <LI><B>Alignment</B> - determines how an item is aligned within the parent layout's allocated space.</LI>
*       <LI><B>MinSize</B> - specifies the smallest dimensions allowed for an item.</LI>
*       <LI><B>MaxSize</B> - specifies the largest dimensions allowed for an item.</LI>
*       <LI><B>OriginalSize</B> - specifies the original dimensions of an item when it was added to a layout.</LI> 
*</UL>
*
*<P>The final value of a property for an item is determined by this order of processing: </P>
*<OL>
*       <LI>A default is set in the GuiLayoutProperties constructor</LI>
*       <LI>Each dialog item type may have its own default, especially in the case of the SizePolicy.</LI>
*       <LI>An item hook or hook handler may set a value in OnInit () or when processing the DITEM_MESSAGE_INIT message.</LI>
*       <LI>When reading the item definition, the extendedIntAttribute values are applied (See "Extended Int Attributes and Overrides" below).</LI>
*       <LI>The 'auxInfo' field override values are applied (See "Extended Int Attributes and Overrides" below).</LI> 
*</OL>
*
* @anchor ExtendedIntAttributesandOverrides
*
*<H3>Extended Int Attributes and Overrides</H3>
*<P>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. </P>
*
* <table>
* <tr>
*   <th>extendedIntAttribute</th>
*   <th>Description</th>
*       <th>auxInfo Override</th>
* </tr>
* <tr>
* <td>EXTINTATTR_MARGIN</td>
* <td>Margin for left, top, right &amp; bottom when in a layout. The default is 0. The units specified are in dialog coordinates.</td>
* <td>margin='l,t,r,b' (see @ref marginOverride)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MARGIN_LEFT</td>
* <td>Left margin when in a layout</td>
* <td>margin= or marginLeft=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MARGIN_TOP</td>
* <td>Top margin when in a layout</td>
* <td>margin= or marginTop=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MARGIN_RIGHT</td>
* <td>Right margin when in a layout</td>
* <td>margin= or marginRight=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MARGIN_BOTTOM</td>
* <td>Bottom margin when in a layout</td>
* <td>margin= or marginBottom=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_SPACING</td>
* <td>Spacing for a Layout. The units specified are in dialog coordinates.</td>
* <td>spacing=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_STRETCH</td>
* <td>Stretch for an item or layout</td>
* <td>stretch= (See @ref StretchFactor)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_DOCK_POSITION</td>
* <td>Dock Position in a DockLayout; valid values come from the DockPosition enum.</td>
* <td>dockPosition= ; valid values are: 'left', 'top', 'right', 'bottom', 'fill'</td>
* </tr>
* <tr>
* <td>EXTINTATTR_COLUMN</td>
* <td>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.</td>
* <td>column=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_COLSPAN</td>
* <td>Column Span in a GridLayout. The default is 1. A value of -1 is the same as the 'Star' value.</td>
* <td>colSpan= (see @ref colSpanOverride)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_ROW</td>
* <td>Row in a GridLayout. The default is 0.</td>
* <td>row=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_ROWSPAN</td>
* <td>Row Span in a GridLayout. The default is 1.</td>
* <td>rowSpan=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_HORIZONTAL_ALIGNMENT</td>
* <td>Horizontal Alignment in a GridLayout or StackLayout; valid values come from the HorizontalAlignment enum. The default is 'stretch'.</td>
* <td>horizontalAlignment= ; valid values are: 'left', 'right', 'center', 'stretch' (see @ref HorizontalAlignment)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_VERTICAL_ALIGNMENT</td>
* <td>Vertical Alignment in a GridLayout or StackLayout; valid values come from the VerticalAlignment enum. The default is 'stretch'.</td>
* <td>verticalAlignment= ; valid values are: 'top', 'bottom', 'center', 'stretch' (see @ref VerticalAlignment)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_HORIZONTAL_SIZEPOLICY</td>
* <td>Horizontal Size Policy; valid values come from the SizePolicyType enum</td>
* <td>sizePolicy= (see @ref sizePolicyOverride)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_VERTICAL_SIZEPOLICY</td>
* <td>Vertical Size Policy; valid values come from the SizePolicyType enum</td>
* <td>sizePolicy= (see @ref sizePolicyOverride)</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MINWIDTH</td>
* <td>Minimum Width when in a layout. The units specified are in dialog coordinates.</td>
* <td>minWidth=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MINHEIGHT</td>
* <td>Minimum Height when in a layout. The units specified are in dialog coordinates.</td>
* <td>minHeight=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MAXWIDTH</td>
* <td>Maximum Width when in a layout. The units specified are in dialog coordinates.</td>
* <td>maxWidth=</td>
* </tr>
* <tr>
* <td>EXTINTATTR_MAXHEIGHT</td>
* <td>Maximum Height when in a layout. The units specified are in dialog coordinates.</td>
* <td>maxHeight=</td>
* </tr>
*</table>
* @note All auxInfo overrides begin with a lower-case letter.
* @note 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 @ref LayoutResourceDefinition.
*
* @anchor marginOverride
*<H3>margin= Override</H3>
*<P>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.</P> 
*
* @anchor sizePolicyOverride
*<H3>sizePolicy= Override</H3>
*<P>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. </P>
*
* @anchor colSpanOverride
*<H3>colSpan= Override</H3>
*<P>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. </P>
*
* @anchor HorizontalAlignment
*<H3>HorizontalAlignment</H3>
*<P> 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.</P>
*
*<table>
* <tr>
*   <th>Member</th>
*   <th>Description</th>
* </tr>
* <tr>
* <td>Left</td>
* <td>Items are aligned to the left of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Center</td>
* <td>Items are aligned to the center of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Right</td>
* <td>Items are aligned to the right of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Stretch (Default)</td>
* <td>Items are stretched to fill the parent layout's allocated layout space.</td>
* </tr>
*</table>
*
* @anchor VerticalAlignment
*<H3>VerticalAlignment</H3>
*<P>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.</P>
*
*<table>
* <tr>
*   <th>Member</th>
*   <th>Description</th>
* </tr>
* <tr>
* <td>Left</td>
* <td>Items are aligned to the top of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Center</td>
* <td>Items are aligned to the center of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Right</td>
* <td>Items are aligned to the bottom of the parent layout's allocated layout space.</td>
* </tr>
* <tr>
* <td>Stretch (Default)</td>
* <td>Items are stretched to fill the parent element's allocated layout space.</td>
* </tr>
*</table>
*
*<H3>Label Items</H3>
*<P>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. </P>
*
*<H4>LABEL_LINKPREV and LABEL_LINKNEXT</H4>
*<P>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.</P>
*
*<H4>LABEL_WORDWRAP</H4>
*<P>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.</P>
*
*@addtogroup MigrationInstructions
*<P> Instructions for migrating MDL Dialogs and Tool Settings to the Layout Manager can be found in the section: @ref LayoutManagerMigration "Migrating to Layout Manager".</P>
*
*@addtogroup Examples
*<H2>Dialog Resource Example</H2>
*<P>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.</P>
*
* @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
*
*<H2>Tool Settings Example </H2>
*<P>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.</P>
*
* @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
*
*<H2> C++ Layout Manager Example </H2>
*<P>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. </P>
* 
* @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
*<P>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.</P>
*
*<table>
        <tr><th>Dialog Item Type</th>
        <th>Default Horizontal Size Policy</th>
        <th>Default Vertical Size Policy</th></tr>
<tr>
<td>ButtonGroup</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>Container</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>ContainerPanel</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>ColorChooser</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>ColorPicker</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>ComboBox</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>CompactSlider</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>FlowDocumentScrollViewer</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>Generic</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>GroupBox</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>IconCmd</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>IconPopup</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>Label</td>
<td>MinimumExpanding</a></td>
<td>Fixed</td>
</tr>
<tr>
<td>Label (with LABEL_WORDWRAP)</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>LevelList</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>ListBox</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>MenuBar</td>
<td>Preferred</td>
<td>Fixed</td>
</tr>
<tr>
<td>MultilineText</td>
<td>MinimumExpanding</td>
<td>MinimumExpanding</td>
</tr>
<tr>
<td>OptionButton</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>PushButton</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>RadioButton</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>Sash (vertical)</td>
<td>Fixed</td>
<td>Expanding</td>
</tr>
<tr>
<td>Sash (horizontal)</td>
<td>Expanding</td>
<td>Fixed</td>
</tr>
<tr>
<td>Scale (vertical)</td>
<td>Fixed</td>
<td>Expanding</td>
</tr>
<tr>
<td>Scale (horizontal)</td>
<td>Expanding</td>
<td>Fixed</td>
</tr>
<tr>
<td>ScrollBar (vertical)</td>
<td>Fixed</td>
<td>Expanding</td>
</tr>
<tr>
<td>ScrollBar (horizontal)</td>
<td>Expanding</td>
<td>Fixed</td>
</tr>
<tr>
<td>Separator (vertical)</td>
<td>Fixed</td>
<td>Expanding</td>
</tr>
<tr>
<td>Separator (horizontal)</td>
<td>Expanding</td>
<td>Fixed</td>
</tr>
<tr>
<td>SpinBox</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>TabPageList</td>
<td>Minimum</td>
<td>Minimum</td>
</tr>
<tr>
<td>Text</td>
<td>Minimum</td>
<td>Fixed</td>
</tr>
<tr>
<td>ToolBox</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>Tree</td>
<td>Preferred</td>
<td>Preferred</td>
</tr>
<tr>
<td>UpDownButtons</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
<tr>
<td>WinFormsControl</td>
<td>Fixed</td>
<td>Fixed</td>
</tr>
</table>
*
* @addtogroup LayoutManagerErrorMessages
*<P>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. </P>
*
*<table>
        <tr><th>Error Message</th>
        <th>Problem Resolution Instructions</th>
<tr>
<td>Parent item for layout instructions is unknown</td>
<td>Layout resource items are only valid in a DialogBoxRsc, DialogItemListRsc or CmdItemListRsc.</td>
</tr>
<tr>
<td>No previous layout item found to add this child layout to</td>
<td>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".</td>
</tr>
<tr>
<td>Item cannot be outside a layout item</td>
<td>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.</td>
</tr>
<tr>
<td>The grid row number is invalid. Using 0.</td>
<td>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.</td>
</tr>
<tr>
<td>The grid column number is invalid. Using 0.</td>
<td>The current column number is less than 0. The default column is 0. Make sure the column='n' syntax is correct.</td>
</tr>
<tr>
<td>Encountered a GridRow outside a GridLayout</td>
<td>The GridRow item may only be located inside a GridLayout / EndLayout block.</td>
</tr>
<tr>
<td>Encountered an EndLayout without a matching "Begin" layout item</td>
<td>The EndLayout item must be matched with a "Begin" layout item. Make sure each "Begin Layout" is properly paired with an "End Layout".</td>
</tr>
<tr>
<td>Spacing item cannot be used in this layout</td>
<td>The Spacing item is only supported in a FlowLayout or StackLayout.</td>
</tr>
<tr>
<td>Stretch item cannot be used in this layout</td>
<td>The Stretch item is only supported in a StackLayout.</td>
</tr>
<tr>
<td>The dialog has no active Layout Manager. Check the layout syntax for the dialog.</td>
<td>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</a> associated with the dialog. Make sure each "Begin Layout" is properly paired with an "End Layout".</td>
</tr>
<tr>
<td>Invalid DockPosition encountered. Valid values are DOCK_TOP, DOCK_BOTTOM, DOCK_LEFT, DOCK_RIGHT and DOCK_FILL.</td>
<td>EXTINTATTR_DOCK_POSITION and SetDockPosition () only accepts the Top, Bottom, Left, Right and Fill values.</td>
</tr>
<tr>
<td>Invalid margin= value encountered. The value should have one, two or four entries.</td>
<td>See an explanation of the margin= syntax in the @ref marginOverride.</td>
</tr>
<tr>
<td>Invalid integer value override encountered.</td>
<td>Several auxInfo override values should be integer values only. Make sure there are no alpha characters included.</td>
</tr>
<tr>
<td>Invalid dockPosition= value encountered. Valid values are 'top', 'bottom', 'left', 'right' and 'fill'.</td>
<td>The dockPosition= auxInfo override value only accepts the Top, Bottom, Left, Right and Fill values.</td>
</tr>
<tr>
<td>Invalid sizePolicy= value encountered. Valid values are 'minimum', 'maximum', 'preferred', 'minimumexpanding', 'expanding' and 'ignored'.</td>
<td>See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride</td>
</tr>
<tr>
<td>Invalid sizePolicy= value encountered. The value should have two entries for horizontal and vertical.</td>
<td>See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride</td>
</tr>
<tr>
<td>Invalid horizontalAlignment= value encountered. Valid values are 'left', 'center', 'right' and 'stretch'.</td>
<td>See an explanation of the horizontalAlignment= syntax in the @ref HorizontalAlignment</td>
</tr>
<tr>
<td>Invalid verticalAlignment= value encountered. Valid values are 'top', 'center', 'bottom' and 'stretch'.</td>
<td>See an explanation of the verticalAlignment= syntax in the @ref VerticalAlignment</td>
</tr>
<tr>
<td>The 'Star' syntax for colSpan= cannot be used for this column because the column number is too large.</td>
<td>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</td>
</tr>
<tr>
<td>The 'Star' syntax for colSpan= only works if you've defined Columns in the <a href="GridLayout" data-wikiword="GridLayout">GridLayout</a> resource.</td>
<td>Make sure the specified GridLayout has an associated GridLayoutRsc definition with column information. See an explanation of the colSpan= syntax in the @ref colSpanOverride</td>
</tr>
</table>
*
*
* @addtogroup LayoutManagerMigration
* 
*<H2>Introduction </H2>
*<P>A Dialog Layout Manager has been added to the MDL Dialog Manager in CONNECT Edition PowerPlatform. 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 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.  </P>
*<P>There are 5 different layout types available in the MDL Layout Manager: </P>
* <OL>
*       <LI><B>GridLayout </B> <P>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.</P></LI> 
*       <LI><B>StackLayout </B> <P>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.</P> </LI>
*       <LI><B>FlowLayout </B> <P>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..</P></LI> 
*       <LI><B>SplitterLayout </B> <P>Puts items on either side of a Sash, or Splitter, control. The SplitterLayout can be either horizontal or vertical.</P></LI> 
*       <LI><B>DockLayout </B> <P>Puts items along the top, bottom, left or right edge. This type of layout is also called a "Border" layout.</P></LI> 
* </OL>
*
*<H2>Layout Manager Concepts</H2>
*<P>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. For details of these concepts, see @ref LayoutManagerConcepts.  </P>
*
*<H2>Guiding Principles </H2>
*<P>Each Dialog and Tool Settings will be different, but there are a number of guiding principles that should be followed when using the Layout Manager. </P> 
*
*<H3>Main Dialog Layouts - Grid, VStack or Dock </H3>
*<P>The GridLayout, VStackLayout or DockLayout are usually used as the main layout for a dialog. The GridLayout is probably the most capable and flexible layout and uses rows and columns. If your dialog is very "blocky", this may be best to start out with. But if the dialog is more free flowing from top to bottom, the VStackLayout might be better as the main layout. The third choice would be the DockLayout, which might be appropriate for a dialog with a menu bar and status bar.  </P>
*
*<H3>Main Tool Settings Layout - VStack</H3>
*<P>The VStackLayout is usually used as the main layout for Tool Settings. When the Tool Settings dialog is docked, it can be any height set by the user. To guarantee that the items are positioned correctly vertically in that scenario, a STRETCH(1) item should be the last item in the VStackLayout in order to prevent the items from being spacing apart too much. </P>
*
*<H3>Use Nested Layouts </H3>
*<P>When specifying the layout of a dialog, numerous layouts can be nested to achieve the overall layout for the dialog. Although the dialog may start with a GridLayout or VStackLayout, you should nest the layouts as deeply as needed to accomplish the overall layout for the dialog. Use a nested FlowLayout to accomplish a "Toolbar" layout. Use a nested HStackLayout for OK/Cancel buttons. Use a nested GridLayout for "Label: Editor" or "Toggle Label: Editor" layouts.  </P>
*
* @anchor ForToolbarButtonsInADialogUseAFlowLayout
*<H3>For Toolbar buttons in a dialog, use a FlowLayout </H3>
*<P>A FlowLayout 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 is perfect for a set of buttons that act as a Toolbar on a dialog. You may also place Separator items between items within the FlowLayout.  </P>
*
*<H3>Use Stretch Factor or Stretch Item before overriding Size Policy</H3>
*<P>Before overriding the Size Policy of an item, consider using a Stretch Factor or Stretch item. The default Size Policies for the items have been established to cover most usages of the items. Therefore, careful thought should be given before overriding that policy. 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. So use of the Stretch Factor should especially be considered before attempting to override an item's Size Policy. </P>
*
*<H2>Common Techniques and How To </H2>
*<P>There are a number of common techniques that can be used in many situations when using the Layout Manager. </P>
*
* @anchor AllowForASeparatorAcrossADialog
*<H3>Allow for a Separator across a dialog </H3> 
*<P>Use a VStackLayout with no margins as the main layout when a Dialog or Tool Settings contains a Separator item that needs to span across the dialog. You will use nested layouts that do have the standard margins and spacing to accomplish the consistent spacing. </P>
*
* @code{.unparsed}
*  BEGIN_VSTACK_LAYOUT(0,"")
*    . . .
*    {AUTO_XYWH,                     Separator,      0,  ON,  SEPARATOR_HORIZONTAL, "", ""},
*    . . .
*   END_LAYOUT
*
* @endcode
*
* @anchor AllowAListBoxItemToBeFlushWithTheDialogEdges  
*<H3>Allow a ListBox item to be flush with the dialog edges </H3>
*<P>Use a VStackLayout with no margins as the main layout when a Dialog or Tool Settings contains a ListBox item that needs to be flush with the left and/or right edge of the dialog. </P>
*
* @code{.unparsed}
*       BEGIN_VSTACK_LAYOUT(0, "")
*               . . .
*                       {{ AUTO_XY, VIEWGROUP_LIST_WIDTH, 0}, ListBox, LISTID_VIEWGROUP_ViewGroups, NO_ITEMARGS},
*               . . .
*       END_LAYOUT
* 
* @endcode
*
*<H3>Allow a MenuBar item to be flush with the dialog edges </H3>
*<P>Use a VStackLayout with no margins as the main layout when a Dialog contains a MenuBar item that needs to be flush with the left and right edges of the dialog. Also, it is recommended to you use the MenuBarX, which includes an MENUBARATTR_TALL attribute and gives more height to the menu bar. </P>
*
* @code{.unparsed}
* DItem_MenuBarXRsc MENUBARID_AppMenu =
*    {
*    NOHOOK, NOARG, MENUBARATTR_TALL,
*        {
*        {PulldownMenu, PULLDOWNMENUID_AppMenu, "", 0, ""},
*        }
*    };
*
* BEGIN_VSTACK_LAYOUT(0, "")
*     {AUTO_XYWH, MenuBarX, MENUID_AppMenu, NO_ITEMARGS},
*     . . .
* END_LAYOUT
*
* @endcode
*
* @anchor PositionOKAndCancelPushButtonsInTheLowerRightCorner 
*<H3>Position OK and Cancel Push Buttons in the lower right corner </H3>
*<P>To position the OK and Cancel buttons in the lower right corner of a modal dialog, in a nested HStackLayout at the bottom of a modal dialog, insert a STRETCH(1) item before the OK and Cancel buttons. The HSTACKLAYOUTID_DialogButtons HStackLayout from ustation.rsc may be used for this purpose. </P>
*
* @code{.unparsed}
* 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

* @endcode
*
*<H3>Center content when using an HStack </H3>
*<P>To center content in an HStackLayout, insert a STRETCH(1) on either side of those items. </P>
*
* @code{.unparsed}
* BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
     STRETCH(1)
     {AUTO_XYWH, PushButton, PUSHBUTTONID_CloseElementCommand, ON, 0, "", ""},
     STRETCH(1)
  END_LAYOUT

* @endcode
*
* @anchor PreventUnwantedVerticalExpansionWhenUsingAVStack
*<H3>Prevent unwanted vertical expansion when using a VStack </H3>
*<P>To prevent unwanted VStackLayout item expansion, insert a STRETCH(1) as the last item in a VStackLayout to push the items above to their normal size and position. This is required for the Tool Settings. </P>
*
* @code{.unparsed}
* BEGIN_VSTACK_LAYOUT(0, "")
    . . .
    STRETCH(1)
 END_LAYOUT

* @endcode
*
* @anchor PreventUnwantedHorizontalExpansionWhenUsingAHStack
*<H3>Prevent unwanted horizontal expansion when using a HStack </H3>
*<P>To prevent unwanted HStackLayout item expansion, insert a STRETCH(1) as the last item in an HStackLayout to push the items to the left to their normal size and position. </P>
* @code{.unparsed}
* BEGIN_HSTACK_LAYOUT(0, "")
    . . .
    STRETCH(1)
 END_LAYOUT

* @endcode
*
* @anchor PreventUnwantedHorizontalExpansionInAGridRow
*<H3>Prevent unwanted horizontal expansion in a GridRow </H3>
*<P>If you want to prevent the columns in a GridRow from expanding too much when a dialog resizes, you can include an extra GridColumnRsc with an increased Stretch Factor in the GridLayoutRsc definition. In this situation, the extra column in the GridRows can remain empty.  </P>
*
* @code{.unparsed}
// Used for "Toggle  Label:  SettingsItem" formatting. Has a stretch at the end to prevent row stretching.
 GridLayoutRsc GRIDLAYOUTID_3ColsToggleLabelSetting =
 {
    {XC_3_2, XC_3_2, XC_3_2, XC_3_2},       // Margins - Left, Top, Right, Bottom
    XC, YC/3,                               // 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 expansion
    }
 };

* @endcode
*
*<H3>Push items to the sides of an HStack </H3>
*<P>If you want to push items to the side in an HStackLayout, include a STRETCH(1) item in the middle of the items. </P>
*
* @code{.unparsed}
        BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
                {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_MyButton, ON, 0, "", ""},
                STRETCH(1)
                {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_Close,    ON, 0, "", ""},
        END_LAYOUT

* @endcode
*
* @anchor AddSpaceBeforeOrAfterAnItem
*<H3>Add space before or after an item </H3>
*<P>To add some space before or after an item, you may put a SPACING item before or after the item. The unit of measurement for the SPACING macro is Dialog Coordinates. There are standard spacing values in dlogbox.r.h, such as GROUPBOX_GAP and SECTION_GAP, which we recommend you use rather than a non-standard calculation that uses XC and YC directly. </P>
*
* @code{.unparsed}
        BEGIN_HSTACK_LAYOUT(HSTACKLAYOUT_LabeledItem, "")
     SPACING(SECTION_GAP)
     {AUTO_XYWH,     Label,   0,                            ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""},
     {AUTO_XYWH,     Text,    TEXTID_RefDialogRotation,     ON, 0, "", ""},
        END_LAYOUT

* @endcode
*
* @anchor MakeOneItemResizable
*<H3>Make one item resizable </H3>
*<P>To make one item resizable within a resizable dialog, set the stretch override to '1' for the item and/or containing layout. In the following example, the ListBox and its containing HStackLayout are set as resizable vertically and horizontally with the stretch='1' override. Whereas, the other content on the dialog will stay at more of a fixed size, only growing as needed according to their Size Policies. </P>
*
* @code{.unparsed}
         BEGIN_VSTACK_LAYOUT(0,"")
     BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_Standard, "stretch='1'")
         {AUTO_XYWH,     ListBox,   LISTBOXID_ToolBoxes,         ON, 0, "", "stretch='1'"},
         . . .
         BEGIN_VSTACK_LAYOUT(VSTACKLAYOUTID_Inner,"")
             . . .
         END_LAYOUT
         . . .
     END_LAYOUT
     . . .
 END_LAYOUT
 
* @endcode
*
* @anchor PositionAndSizeAnItemsLabel
*<H3>Position and Size an item's label </H3> 
*
*<P>To correctly position and size the label for a dialog item using the Layout Manager, use a separate Label with a LABEL_LINKPREV or LABEL_LINKNEXT attribute in the itemArg field. LABEL_LINKPREV will pull the label string from the previous item, and LABEL_LINKNEXT will pull the label string from the next item. Using this technique, the two items are "linked" for focus model purposes. This allows the main item to keep the label in its resource definition in case it is used outside a layout, but also allows the Label item to "link" to it and specify an independent column and size policy for layout purposes. The label string can grow independently and will automatically be accommodated by the Layout Manager. You may also specify alignment for the Label using ALIGN_LEFT (default), ALIGN_CENTER or ALIGN_RIGHT.  </P>
*
*<H4>LABEL_LINKPREV </H4>
* @code{.unparsed}
* BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "")
     GRID_ROW(0, "")
         {{AUTO_XY, 0, 0},       ToggleButton,   TOGGLEID_Length, ON, 0, "", ""},
         {{AUTO_XY, W10, 0},     Label,          0, ON, LABEL_LINKPREV, "", ""},    // Pull label from ToggleButton
         {{AUTO_XY, W10, 0},     Text,           TEXTID_Length, ON, 0, "", ""},
     END_ROW
     . . .
  END_LAYOUT
  
* @endcode
*
*<H4>LABEL_LINKNEXT </H4>
* @code{.unparsed}
* BEGIN_GRID_LAYOUT(GRIDLAYOUTID_2ColsLabelSetting, "")
     GRID_ROW(0, "")
         {{AUTO_XY, W10, 0},     Label,          0, ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""},   // Pull label from OptionButton
         {{AUTO_XY, 0, 0},       OptionButton,   OPTIONBUTTONID_ElementFill, ON,  0, "", ""},
     END_ROW
     . . .
  END_LAYOUT
  
* @endcode
*
*<P>There are convenience macros defined in dlogbox.r.h that simplify working with Labels for layout. These include:  </P>
*<UL>
* <LI>LAYOUT_LABEL_PREV_LEFT - link to previous item, align left  </LI>
* <LI>LAYOUT_LABEL_PREV_RIGHT - link to previous item, align right </LI>
* <LI>LAYOUT_LABEL_NEXT_LEFT - link to next item, align left  </LI>
* <LI>LAYOUT_LABEL_NEXT_RIGHT - link to next item, align right </LI>
*</UL>
*
*<H3>Labeled Item in a FlowLayout </H3>
*<P>To correctly position and size an item and label within a FlowLayout, use a nested HStackLayout within the FlowLayout and use the LABEL_LINKNEXT attribute on the Label. You may also put a SPACING item before the Label to give it more room. To center the Label and linked Item vertically, add a verticalAlignment override of 'center' to the HStackLayout. </P>
*
* @code{.unparsed}
* BEGIN_FLOW_LAYOUT(FLOWLAYOUTID_IconButtons, "")
     . . .
     BEGIN_HSTACK_LAYOUT(HSTACKLAYOUT_LabeledItem, "verticalAlignment='center'")
         SPACING(XC/2)
         {AUTO_XYWH,     Label,   0,                            ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""},
         {AUTO_XYWH,     Text,    TEXTID_RefDialogRotation,     ON, 0, "", ""},
     END_LAYOUT
     . . .
   END_LAYOUT
*
* @endcode
*
* @anchor SetTheMinimumSizeForAListBox
*<H3>Set the Minimum Size for a ListBox</H3> 
*<P>Since the Size Policy for a ListBox (also the Tree a few others) is 'Preferred, Preferred', the ListBox size can be shrunk down to its minimum size. To set the minimum size for the dialog, set the EXTINTATTR_MINWIDTH and EXTINTATTR_MINHEIGHT extended attributes in the resource definition of the ListBox. The unit of measurement for these extended attributes is Dialog Coordinates. Therefore, XC and YC may be used. </P>
*
* @code{.unparsed}
* DItem_ListBoxRsc LISTBOXID_ToolBoxes =
     {
     NOHELP, MHELP, HOOKID_ListBoxStd, NOARG,
     LISTATTR_DRAWPREFIXICON|LISTATTR_DYNAMICSCROLL|LISTATTR_FONTBYCOLUMN|LISTATTR_HORIZSCROLLBAR,
     10, 0, "",
         {
         {30*XC, 60, 0, TXT_Show_ToolBoxes},
         }
     }
 extendedIntAttributes
     {{
         EXTINTATTR_MINWIDTH,  30*XC,
         EXTINTATTR_MINHEIGHT, 12*YC
     }};
* @endcode
*
*<H3>Span a cell across multiple columns </H3>
*<P>To span a GridLayout cell across multiple columns, use the colSpan='value' override for an item. The value for colSpan= may either be the number of columns to span or a '*', which mean span to the end of the row. In the example below, the 2nd column in the 2nd GridRow spans across the 2nd and 3rd columns. </P>
*
* @code{.unparsed}
* BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "")
     GRID_ROW(0, "")
         {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEID_UseFence,             ON, CMD_CHANGE_ATTRIBUTES, "", ""},
         {{AUTO_XY, CA_CKBX_CX*XC, 0},   Label,          0,                             ON, LABEL_LINKPREV, "", ""},
         {{AUTO_XY, CA_CTRL_CX*XC, 0},   OptionButton,   OPTIONBUTTONID_LockFenceMode,  ON, 0, "\0", ""},
     END_ROW
     GRID_ROW(0, "")
         {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEBUTTONID_MakeCopy,       ON, 0, "", ""},
         {{AUTO_XY, CA_CKBX_CX*XC, 0},   Label,          0,                             ON, LABEL_LINKPREV, "", "colSpan='*'"},
     END_ROW
     . . .
 END_LAYOUT

* @endcode
*
*
* @addtogroup MigratingDialogs
*
*<P>This section will take two dialogs and migrate them from their older version to using the Layout Manager. </P>
*
*<H2>Manage View Groups Dialog</H2>
*<P>The Manage View Groups dialog is already resizable. It contains a toolbar with 3 buttons at the top, a ListBox in the middle and a couple of buttons at the bottom. The only layout problem, according to the UI Guidelines, is that the buttons are centered in the dialog. So one goal is to move those buttons to the lower right hand corner. Other than that, the overall layout can remain the same. </P>
*
*<H3>Before Image </H3>
* @image html "images/ViewGroups-Before.png"
*
*<H3>After Image </H3>
* @image html "images/ViewGroups-After.png"
*<P>For the overall layout, we'll use a VStackLayout. It allows you to add items from top to bottom. For the toolbar buttons at the top, we'll use a FlowLayout, and it will be the first item in the VStackLayout. We'll use the standard FLOWLAYOUTID_IconButtons FlowLayout definition, which is built into ustation.rsc. Notice the use of the AUTO_XYWH helper macro, which indicates the default size of the item will be used and the Layout Manager will determine the position. </P>
*<P>The ListBox itself will be the second item. It needs no other layout container. We give it a stretch factor of 1 so it gets more space vertically as the dialog is resized larger. </P>
*<P>The buttons at the bottom will be put into an HStackLayout, and a Stretch item will be placed at the beginning of it to push the buttons to the right. The Stretch item is given a stretch factor of 1 so it gets more space horizontally as the dialog is resized larger. We use the standard HSTACKLAYOUTID_DialogButtons HStackLayout definition, which is built into ustation.rsc. For standardization of margins and spacing, layouts defined in ustation.rsc should be used when possible.  </P>
*<P>This example uses the following common techniques: </P>
*<UL>
*       <LI>@ref ForToolbarButtonsInADialogUseAFlowLayout "For Toolbar buttons in a dialog, use a FlowLayout"</LI>
*       <LI>@ref AllowAListBoxItemToBeFlushWithTheDialogEdges "Allow a ListBox Item to be flush with the dialog edges" </LI>
*       <LI>@ref MakeOneItemResizable "Make one item resizable"</LI>
*       <LI>@ref PositionOKAndCancelPushButtonsInTheLowerRightCorner "Position OK and Cancel Push Buttons in the lower right corner" </LI>
*</UL>
*
*<H3>Before </H3> 
*
* @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,
    {
 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Create))                  // @fadoc 'Create View Group' ...
        {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Create, ON, 0, "", ""},
 @endif
 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Properties))              // @fadoc 'Edit View Group Properties' ...
        {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Properties, ON, 0, "", ""},
 @endif
 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Delete))                  // @fadoc 'Delete View Group' ...
        {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Delete, ON, 0, "", ""},
 @endif
    {{ PANEL_ITEM_X, VIEWGROUP_LIST_Y, VIEWGROUP_LIST_WIDTH, 0},
        ListBox, LISTID_VIEWGROUP_ViewGroups, ON, 0, "", ""},
    {{ RIGHT_CENTER_BUTTON_X, PANEL_ITEM_ROW_AFTER_LIST(1), BUTTON_STDWIDTH*2, 0},
        PushButton, PUSHBUTTONID_VIEWGROUP_Apply, ON, 0,"", ""},
    {{ LEFT_CENTER_BUTTON_X, PANEL_ITEM_ROW_AFTER_LIST(1), BUTTON_STDWIDTH*2,0},
        PushButton, PUSHBUTTONID_VIEWGROUP_Close,  ON, 0, "", ""},
    }
    };
*
* @endcode
*
*<H3>After </H3>
*<P>From usation.rsc </P>
*
* @code (.unparsed)
* // Used for Icon Buttons in a FlowLayout resembling a Toolbar at the top or bottom of a dialog
 FlowLayoutRsc FLOWLAYOUTID_IconButtons =
 {
    {1, 1, 1, 1},                           // Margins - Left, Top, Right, Bottom
    1, 1                                    // HSpacing, VSpacing
 };

 // Used for OK/Cancel buttons at the bottom of a dialog
 HStackLayoutRsc HSTACKLAYOUTID_DialogButtons =
 {
    {XC_3_2, XC_3_2, XC_3_2, XC_3_2},       // Margins - Left, Top, Right, Bottom
    XC_3_2                                  // Spacing
 };
*
* @endcode
*
*<P>From view group code </P>
*
* @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, "")
@if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Create))       // @fadoc 'Create View Group' ...
            {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Create, NO_ITEMARGS},
@endif
@if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Properties))   // @fadoc 'Edit View Group Properties' ... 
            {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Properties, NO_ITEMARGS},
@endif
@if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Delete))       // @fadoc 'Delete View Group' ... 
            {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Delete, NO_ITEMARGS},
@endif
        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
*
*<H2>Tool Boxes Dialog </H2>
*<P>The ToolBoxes dialog was not resizable before. So one goal is to make it resizable. The old version of the dialog has quite a bit of wasted space, as well. So another goal is to move some of the items to new locations in order to give more space to the ListBox, which is the main item on this dialog. The old dialog had an OptionButton above the ListBox, 3 Toggles below the ListBox and Remove and Customize buttons to the right of the ListBox. So we'll put all of those items to the right of the ListBox, which will help give it more space. Another goal is to move the OK and Cancels buttons to the lower right hand corner to adhere to the UI Guidelines. </P>
*
*<H3>Before Image</H3> 
* @image html "images/ToolBoxes-Dialog-Before.png"
*
*<H3>After Image</H3>
* @image html "images/ToolBoxes-Dialog-After.png"
*
*<P>To make an MDL dialog resizable, we add the DIALOGATTR_GROWABLE attribute to the list of dialog attributes. We start the layout of the dialog with a VStackLayout. The ListBox will now be placed in the upper left hand corner of the dialog, and the settings and other buttons will be placed to the right of the ListBox. In order to achieve this, we place an HStackLayout as the first item in the VStackLayout and place the ListBox as the first item of the HStackLayout. We give both the HStackLayout and the ListBox a stretch factor of 1 so they get more space horizontally and vertically as the dialog is resized larger. We set the minimum size for the ListBox in its resource definition using the EXTINTATTR_MINWIDTH and EXTINTATTR_MINHEIGHT extended attributes (shown above - @ref SetTheMinimumSizeForAListBox "Set the Minimum Size for a ListBox". </P>
*
*<P>Since we want several items to be at the right of the ListBox, we can group those in a VStackLayout by adding each item with appropriate spacing between using the SPACING helper macro. At the end of the VStackLayout, we add a STRETCH(1) to prevent the items in the VStackLayout from expanding vertically. We add the VStackLayout containing the settings and buttons to the HStackLayout after some space.  </P>
*
*<P>The OK and Cancel buttons at the bottom are put into an HStackLayout, and a Stretch item will be placed at the beginning of it to push the buttons to the right. The Stretch item is given a stretch factor of 1 so it gets more space horizontally as the dialog is resized larger. As with the "Managed View Groups" dialog, we use the standard HSTACKLAYOUTID_DialogButtons HStackLayout definition, which is built into ustation.rsc. For standardization of margins and spacing, layouts defined in ustation.rsc should be used when possible. </P>
*
*<P>Several of the older helper macros dealing with column position and row calculations could be removed after migrating to the Layout Manager. </P>
*
*<P>This example uses the following common techniques: </P>
*<UL>
*       <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
*       <LI>@ref MakeOneItemResizable "Make one item resizable"</LI>
*       <LI>@ref SetTheMinimumSizeForAListBox "Set the Minimum Size for a ListBox"</LI>
*       <LI>@ref AddSpaceBeforeOrAfterAnItem "Add space before or after an item"</LI>
*       <LI>@ref PositionOKAndCancelPushButtonsInTheLowerRightCorner "Position OK and Cancel Push Buttons in the lower right corner" </LI>
*</UL>
*
*<H3>Before </H3>
*
* @code (.uparsed)
* #define X1 (1*XC)               // text & option button x position 
    #define X2 (2.5*XC)
    #define X3 (XSIZE/2)
    #define X4 (3.5*XC)
    #define Y1 (GENY(1))
    #define YGBOX (Y1+YC/2)
    #define YLBOX (YGBOX+YC)
    #define YLABEL (GENY(12))
    #define Y2 (Y1+2*YC)
    #define Y3 (Y2+3*YC)
    #define Y4 (Y3+2*YC)
    #define Y5 (Y4+2*YC)
    #define Y6 (Y5+3*YC)

    #define YSEP        (GENY(12) + 1.5*YC) // Microsoft Standard says 10 pixels below list box 
    #define SEP_WIDTH   (XSIZE - 2*X1)
    #define GBOX_HEIGHT (YLABEL+(1.5*YC)-YGBOX)
    #define GBOX_WIDTH  (XBUT-35+XC)

    #define YTOGGLE1    (YSEP + 10)
    #define YTOGGLE2    (YTOGGLE1 + YC+BGAP)
    #define YTOGGLE3    (YTOGGLE2 + YC+BGAP)

    #define XBUT (X2+32*XC+ 35) // Microsoft standard says 35 pixels from the right margin of the list box 

    #define BUTTON_WIDTH (BUTTON_STDWIDTH + 10*XC)

    DialogBoxRsc DIALOGID_OpenToolBox =
        {
        DIALOGATTR_DEFAULT|DIALOGATTR_MODAL|DIALOGATTR_ALWAYSSETSTATE,
        XSIZE, YSIZE,
        NOHELP, MHELP, HOOKID_Dialog_OpenToolBox, NOPARENTID,
        TXT_OpenToolBoxTitle,
    {
    {{X2,YLBOX,0,0},        ListBox,   LISTBOXID_ToolBoxes,         ON, 0, "", ""},
    {{X2,Y1,0,0},   OptionButton,   OPTIONBUTTONID_ListType, ON, 0, "", ""},
    {{X2,YLABEL,0,0}, Label,   0, ON, LABEL_FONT_BOLD, TXT_Label_FramesBold, ""},
    {{XBUT, Y1,BUTTON_WIDTH,0}, PushButton,  PUSHBUTTONID_OK, ON, 0,"", ""},
    {{XBUT, Y2,BUTTON_WIDTH,0}, PushButton,  PUSHBUTTONID_Cancel, ON, 0, "", ""},
    {{XBUT, Y3,BUTTON_WIDTH,0}, PushButton,  PUSHBTNID_Reset, ON, 0, "", ""},
    {{XBUT, Y4,BUTTON_WIDTH,0}, PushButton,  PUSHBTNID_Customize, ON, 0, "", ""},
    {{X1,   YSEP, SEP_WIDTH,0}, Separator,    0, ON, 0, "", ""},
    {{X1,   YTOGGLE1, 0,0}, ToggleButton,    TOGGLEBTNID_LargeBtns, ON, 0, "", ""},
    {{X1,   YTOGGLE2, 0,0}, ToggleButton,    TOGGLEBTNID_ToolTips, ON, 0, "", ""},
    {{X1,   YTOGGLE3, 0,0}, ToggleButton,    TOGGLEBTNID_ImmediatelyOpen, ON, 0, "", ""},
    }
        };
*
* @endcode
*
*<H3>After </H3>
*
* @code (.unparsed)
* #define XSIZE           (100*XC)
 #define YSIZE           (30*YC) 

 #define BUTTON_WIDTH    BUTTON_LARGEWIDTH

 VStackLayoutRsc 1 =
 {
     {0, 0, 0, 0},
     YC/3
 };

 DialogBoxRsc DIALOGID_OpenToolBox =
     {
     DIALOGATTR_DEFAULT|DIALOGATTR_MODAL|DIALOGATTR_ALWAYSSETSTATE|DIALOGATTR_GROWABLE,
     XSIZE, YSIZE,
     NOHELP, MHELP, HOOKID_Dialog_OpenToolBox, NOPARENTID,
     TXT_OpenToolBoxTitle,
 {
 BEGIN_VSTACK_LAYOUT(0,"")
     BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "stretch='1'")
         {AUTO_XYWH,     ListBox,        LISTBOXID_ToolBoxes, ON, 0, "", "stretch='1'"},
         SPACING(XC)
         BEGIN_VSTACK_LAYOUT(1,"")
             {AUTO_XYWH, OptionButton,   OPTIONBUTTONID_ListType, ON, 0, "", ""},
             SPACING(YC)
             {AUTO_XYWH, ToggleButton,   TOGGLEBTNID_LargeBtns, ON, 0, "", ""},
             {AUTO_XYWH, ToggleButton,   TOGGLEBTNID_ToolTips, ON, 0, "", ""},
             {AUTO_XYWH, ToggleButton,   TOGGLEBTNID_ImmediatelyOpen, ON, 0, "", ""},
             SPACING(YC)
             {{AUTO_XY,BUTTON_WIDTH,0},  PushButton,     PUSHBTNID_Reset, ON, 0, "", ""},
             {{AUTO_XY,BUTTON_WIDTH,0},  PushButton,     PUSHBTNID_Customize, ON, 0, "", ""},
             STRETCH(1)
         END_LAYOUT
     END_LAYOUT

     BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
         STRETCH(1)
         {{AUTO_XY,BUTTON_WIDTH,0}, PushButton,  PUSHBUTTONID_OK, ON, 0,"", ""},
         {{AUTO_XY,BUTTON_WIDTH,0}, PushButton,  PUSHBUTTONID_Cancel, ON, 0, "", ""},
     END_LAYOUT
 END_LAYOUT
 }};
*
* @endcode
*
*
* @addtogroup MigratingToolSettings
*
*<H2>Place Line </H2>
*<P>The following example is the "Place Line" command. It has three sets of a ToggleButton followed by a Text field. The third set is hidden by default. We will not change the actual layout of this command's settings.  </P>
*
* <H3>Before Image</H3>
* @image html "images/PlaceLineTS.png"

* <H3>After Image</H3>
* @image html "images/CONSGEOM_600_PlaceLine.png"
*
*<P>To migrate the settings to the Layout Manager, we start with a VStackLayout as its main layout and put a GridLayout within it with three rows. The GridLayout is not used as the main layout because we need to push the items up from the bottom when the Tool Settings dialog is docked, and we do that with a STRETCH(1) item at the end of a VStackLayout. 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, but 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. The items in the third row are hidden by default; therefore, that row's height is 0. A STRETCH(1) is inserted as the last item in the VStackLayout to prevent unnecessary row height expansion when the Tool Settings dialog is docked. </P>
*
*<P>This example uses the following principle and common techniques:  </P>
*<UL>
*       <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
*       <LI>@ref PreventUnwantedHorizontalExpansionInAGridRow "To prevent unwanted horizontal expansion in a GridRow" </LI>
*       <LI>@ref PositionAndSizeAnItemsLabel "Position and Size an item's label" </LI>
*</UL>
*
*<H3>Before </H3>
*
* @code (.unparsed)
* #define W10             10*XC

 CmdItemListRsc CMD_PLACE_LINE_CONSTRAINED =
 {
     {
 {{X1, Y1, 0, 0},        ToggleButton,   TOGGLEID_Length, ON, 0, "", ""},
 {{X15, Y1, W10, 0},     Text,           TEXTID_Length, ON, 0, "", ""},
 {{X1, Y2, 0, 0},        ToggleButton,   TOGGLEID_Angle, ON, 0, "", ""},
 {{X15, Y2, W10, 0},     Text,           TEXTID_Angle, ON, 0, "", ""},
 {{X1, Y3, 0, 0},        ToggleButton,   TOGGLEID_SolutionChoice, ON|HIDDEN, 0, "", ""},
 {{X15, Y3, W10, 0},     OptionButton,   OPTIONBUTTONID_SolutionChoice, ON|HIDDEN, 0, "", ""},
 {{X1,  Y3, W10, 0},     Label,          0,                              ON, 0, "", ""},
     }
 };
*
* @endcode
*
*<H3>Before </H3>
*
* <P>From MicroStation  </P>
*
* @code (.unparsed)
* 
* // Use for all 3 column Grids in Tool Settings
GridLayoutRsc GRIDLAYOUTID_ToolSettings3Cols =
{
    {0, 0, 0, 0},                                               // Margins - Left, Top, Right, Bottom
    GRID_HSPACING, GRID_VSPACING,                               // HSpacing, VSpacing
    {                                                           // Column Definitions
        {0, "ts3_column0"},                                     // Stretch, SharedSizeGroup
        {0, "ts3_column1"},
        {0, "ts3_column2"},
        {1, "ts3_stretch"},                                     // Extra column with a Stretch Factor of 1 to prevent unwanted row expansion
    }
};
*
* @endcode
*
*<P>From PPModules\2dModeling\Apps\consgeom\transkit\consgeom.r </P>
*
* @code (.unparsed)
*#define W10             10*XC

 CmdItemListRsc ItemList_LineConstrained =
 {{
 BEGIN_TOOL_SETTINGS
     BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
         GRID_ROW(0, "")
             {{AUTO_XY, 0, 0},           ToggleButton,   TOGGLEID_Length, ON, 0, "", ""},
             {{AUTO_XY, W10, 0},         Label,          0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
             {{AUTO_XY, W10, 0},         Text,           TEXTID_Length, ON, 0, "", ""},
         END_ROW
         GRID_ROW(0, "")
             {{AUTO_XY, 0, 0},           ToggleButton,   TOGGLEID_Angle, ON, 0, "", ""},
             {{AUTO_XY, W10, 0},         Label,          0, ON, LABEL_LINKPREV| ALIGN_RIGHT, "", ""},
             {{AUTO_XY, W10, 0},         Text,           TEXTID_Angle, ON, 0, "", ""},
         END_ROW
         GRID_ROW(0, "")
             {{AUTO_XY, 0, 0},           ToggleButton,   TOGGLEID_SolutionChoice, ON|HIDDEN, 0, "", ""},
             {{AUTO_XY, W10, 0},         Label,          LABELID_SolutionChoice, ON|HIDDEN, LABEL_LINKPREV| ALIGN_RIGHT, "", ""},
             {{AUTO_XY, W10, 0},         OptionButton,   OPTIONBUTTONID_SolutionChoice, ON|HIDDEN, 0, "", ""},
         END_ROW
     END_LAYOUT
 END_TOOL_SETTINGS
 }};
* 
* @endcode
*
*<H2>Change Attributes </H2>
*
*<P>The following example is the "Change Attributes" command. </P>
<H3>Before Image</H3>
* @image html "images/ChangeAttributesTS.png"

*<H3>After Image</H3>
* @image html "images/CHANGEATTRIBS_3800_ChangeAttributes.png"
*
*<P> These settings basically have 3 sections:</P>
*<OL>
*       <LI>The "Use Active Attributes" section </LI>
*       <LI>Several "Toggle Label: Editor" rows </LI>
*       <LI>more Toggles, one with an editor, and two without  </LI>
*</OL>
*
*<P>The sections are separated by a Separator item, which spans across the width of the dialog. The basic layout of the command's settings will remain unchanged. </P>
*
*<P>To migrate the settings to the Layout Manager, we start with a VStackLayout as its main layout. For the first section, we use an HStackLayout. We use the HSTACKLAYOUTID_DialogButtons from ustation.rsc. To layout the label of the ToggleButton properly, 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. A SPACING(XC) is used before the IconCmdX to add spacing between the items. A STRETCH(1) is inserted as the last item in the HStackLayout to prevent unnecessary horizontal expansion. The first Separator is then added directly to the VStackLayout.  </P>
*
*<P>The next section contains several "Toggle Label: Editor" rows. The layout for this section is a GridLayout, and we use the GRIDLAYOUTID_3ColsToggleLabelSetting standard layout from ustation.rsc. Each "Toggle Label: Editor" set will be on a separate GridRow. This is accomplished using the GRID_ROW and END_ROW helper macros. We again add a Label item with the "LABEL_LINKPREV" itemArg for proper layout and sizing. After the GridLayout, the second Separator is added directly to the VStackLayout.  </P>
*
*<P>The final section is another GridLayout using the same GRIDLAYOUTID_3ColsToggleLabelSetting standard layout. The first GridLayout is similar to the ones in the previous section. But the last two have no editor. So we use a colSpan override value of '*' (AKA. the Star value), which indicates the cell will span the columns to the end of the row. The last item added to the main VStackLayout is a STRETCH(1) item to prevent vertical stretching. </P>
*
*<P>Several of the older helper macros dealing with column position and row calculations could be removed after migrating to the Layout Manager.  </P>
*
*<P>This example uses the following principle and common techniques:  </P>
*
*<UL>
*       <LI>@ref AddSpaceBeforeOrAfterAnItem "Add space before or after an item"</LI>
*       <LI>@ref PreventUnwantedHorizontalExpansionWhenUsingAHStack "Prevent unwanted horizontal expansion when using a HStack" </LI>
*       <LI>@ref AllowForASeparatorAcrossADialog "Allow for a Separator across a dialog" </LI>
*       <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
*       <LI>@ref PreventUnwantedHorizontalExpansionInAGridRow "To prevent unwanted horizontal expansion in a GridRow" </LI>
*       <LI>@ref PositionAndSizeAnItemsLabel "Position and Size an item's label" </LI>
*</UL>
*
*<H3>Before</H3>
*
* @code (.unparsed)
*
* #define CA_CTRL_CX  17
 #define CA_CKBX_CX  16
 #define CA_UAA_CX   (20*XC)
 #define CA_MElm_X   (22*XC)
 #define CA_ROW(x)   D_ROW(x)
 #define CA_CTRL_X   (17*XC)

 CmdItemListRsc CMD_CHANGE_ATTRIBUTES =
    {{
        {{XC,        CA_ROW( 1.0), CA_UAA_CX,     0}, ToggleButton, TOGGLEBUTTONID_UseActiveAttributes,   ON,       0,  "", ""},
        {{CA_MElm_X, CA_ROW( 0.8), 0,             0}, IconCmdX,     ICONCMDX_MatchElementAttr,            ON,       0,  "", ""},
        {{0,         CA_ROW( 2.2), 0,             0}, Separator,    0,                                    ON,       0,  "", ""},
        {{XC,        CA_ROW( 2.7), CA_CKBX_CX*XC, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmLevel,        ON,       0,  "", ""},
        {{CA_CTRL_X, CA_ROW( 2.7), CA_CTRL_CX*XC, 0}, ComboBox,     COMBOBOXID_ElmLevel,                  DISABLED, 0,  "", ""},
        {{XC,        CA_ROW( 3.7), CA_CKBX_CX*XC, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmOutlineColor, ON,       0,  "", ""},
        {{CA_CTRL_X, CA_ROW( 3.7), CA_CTRL_CX*XC, 0}, IconPopup,    ICONPOPUPID_ElmOutlineColor,          DISABLED, 0,  "", ""},
        . . .
        {{0,         CA_ROW(10.8), 0,             0}, Separator,    0,                                    ON,       0,  "", ""},
        {{XC,        CA_ROW(11.2), 0,             0}, ToggleButton, TOGGLEID_UseFence,                    ON, CMD_CHANGE_ATTRIBUTES,"",""},
        {{15*XC,     CA_ROW(11.2), 0,             0}, OptionButton, OPTIONBUTTONID_LockFenceMode,         ON,       0,  "\0", ""},
        {{XC,        CA_ROW(12.2), 0,             0}, ToggleButton, TOGGLEBUTTONID_MakeCopy,              ON,       0,  "", ""},
        . . .
    }};
*
* @endcode
*
*<H3>After </H3>
*
*@code (.unparsed)
* #define CA_CTRL_CX  17
 #define CA_CKBX_CX  12

CmdItemListRsc ItemList_ChangeAttributes =
    {{
    BEGIN_TOOL_SETTINGS
        BEGIN_VSTACK_LAYOUT (VSTACKLAYOUTID_Inner, "")
            BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
                GRID_ROW(0, "")
                    EMPTY_GRID_CELL(0,"")
                    EMPTY_GRID_CELL(0,"")
                    BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_ToolSettingsButtons, "column='2',colSpan='*'")
                        {{AUTO_XY, 0,   0},         ToggleButton,   TOGGLEBUTTONID_UseActiveAttributes,     ON,          0,  "",     ""},
                        {{AUTO_XY, 0,   0},         IconCmdX,       ICONCMDX_MatchElementAttr,              ON,          0,  "",     ""},
                    END_LAYOUT
                END_ROW
            END_LAYOUT

            {AUTO_XYWH,                             Separator,      0,  ON,  SEPARATOR_HTOOLSETTINGS, "", ""},

            BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
                GRID_ROW(0, "")
                    {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEBUTTONID_ChangeElmLevel,          ON,          0,  "",     ""},
                    {{AUTO_XY, CA_CKBX_CX*XC, 0},   Label,          0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
                    {{AUTO_XY, CA_CTRL_CX*XC, 0},   ComboBox,       COMBOBOXID_ElmLevel,                    DISABLED,    0,  "",     ""},
                END_ROW
                GRID_ROW(0, "")
                    {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEBUTTONID_ChangeElmOutlineColor,   ON,          0,  "",     ""},
                    {{AUTO_XY, CA_CKBX_CX*XC, 0},   Label,          0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
                    {{AUTO_XY, CA_CTRL_CX*XC, 0},   IconPopup,      ICONPOPUPID_ElmOutlineColor,            DISABLED,    0,  "",     ""},
                END_ROW
. . .         
            END_LAYOUT

            {AUTO_XYWH,                             Separator,      0,  ON,  SEPARATOR_HTOOLSETTINGS, "", ""},
        
            BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
                GRID_ROW(0, "")
                    {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEID_UseFence,                      ON, CMD_CHANGE_ATTRIBUTES, "", ""},
                    {{AUTO_XY, CA_CKBX_CX*XC, 0},   Label,          0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
                    {{AUTO_XY, CA_CTRL_CX*XC, 0},   OptionButton,   OPTIONBUTTONID_LockFenceMode,           ON,          0,  "\0",   ""},
                END_ROW
                GRID_ROW(0, "")
                    {{AUTO_XY, 0,   0},             ToggleButton,   TOGGLEBUTTONID_MakeCopy,                ON,          0,  "",     "column='2',colSpan='*'"},  
                END_ROW
. . .
            END_LAYOUT

            STRETCH (1)
        END_LAYOUT
    END_TOOL_SETTINGS
    }};
    }};
*
* @endcode
*
*
*
*
*
*
*
*
*
*****************************************************************************************/

/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/




















@endcode

<P> And an example of XCommand definition is shown below. </P>

@code{.unparsed}

        {"DrawingAids.Locks.Axis", 
        {CMD_LOCK_AXIS_TOGGLE, MTASKID, ""},    
        "AxisLock", 
        TXT6_SettingsSubLockAxis,
        "",
        "DrawingAids.Locks.Axis", "", "", "[ActiveLock]ActiveLock.AxisLockEnabled()", "", NOACCEL, 
        PP_ID_FeatureAspects_DrawingAids_Locks_Axis},   // @fadoc  DrawingAids.Locks.Axis XCommand

        {"DrawingAids.Locks.ConstructSnap", 
        {CMD_LOCK_SNAP_ACS_TOGGLE, MTASKID, ""},    
        "ACSSnapLock", 
        TXT6_SettingsSubLockConstructSnap,
        "",
        "DrawingAids.Locks.ConstructSnap", "", "", "[ActiveLock]ActiveLock.ConstructionPlaneLockEnabled()", "", NOACCEL, 
        PP_ID_FeatureAspects_DrawingAids_Locks_SettingsMenu},   // @fadoc  DrawingAids.Locks.ConstructSnap XCommand
 

@endcode


<H4>User Defined XCommands</H4>

<P>User defined XCommands are defined in XML files. Below is an example of XML defined commands. </P>

@code{.unparsed}
<UserNamedCommands>
    <UserNamedCommand>
        <Name>GeneralExample.PlaceThickCircle</Name>
        <Label>Thick Circle</Label>
        <Description>Place thick circle</Description>
        <Keyin>[CONSGEOM]PLACE CIRCLE ICON;co=4;wt=4;lc=0</Keyin>
        <IconName>PlaceCircle</IconName>
    </UserNamedCommand>
    <UserNamedCommand>
        <Name>GeneralExample.ToolWithNoIcon</Name>
        <Label>Place Line</Label>
        <Description>Place Line (No Icon)</Description>
        <Keyin>PLACE LINE;co=4;wt=4;lc=0</Keyin>
    </UserNamedCommand>
    <UserNamedCommand>
        <Name>GeneralExample.PlaceThinShape</Name>
        <Label>Thin Shape</Label>
        <Description>Place thin shape</Description>
        <Keyin>[CONSGEOM]PLACE SHAPE CONSTRAINED;co=1;wt=0;lc=0</Keyin>
        <IconName>PlaceShape</IconName>
    </UserNamedCommand>
    <UserNamedCommand>
        <Name>GeneralExample.PlaceSolidSlab</Name>
        <Label>Place Slab</Label>
        <Description>Place slab</Description>
        <Keyin>[SOLIDMODELING]PLACE SLAB ICON;co=5;wt=2;lc=0</Keyin>
        <IconName>PlaceSlab</IconName>
        <VisibilityExpression>[Session]Session.TreatActiveModelAs3D()</VisibilityExpression>
    </UserNamedCommand>
</UserNamedCommands>
@endcode

<H3>Example <CommandData> Specifications</H3>
<P>The XML format supports multiple types of Command specification. The recommended Command Type is NamedCommand.</P> 

<H4>NamedCommand </H4>
<P>The example below shows that in addition to specifying the name of the XCommand, the XML can also define Command Parameters and supply an icon to override the one defined in the XCommand resource. </P>

@code{.unparsed}

<CommandData Type="NamedCommand">
    <NamedCommand>Mstn.Cells.CellSelector
        <CmdParameters>CELLSEL DIALOG CELLSEL</CmdParameters>
        <Icon Type="NamedIcon">
            <NamedIcon>Cell</NamedIcon>
        </Icon>
    </NamedCommand>
</CommandData>

@endcode

<H4>UserKeyinCommand </H4>
<P>The example below shows the definition of the key-in to queue, the icon to use, and the label and desciption to use for the Button Label and ToolTip text. </P>

@code{.unparsed}

<CommandData Type="UserKeyinCommand">
    <UserKeyinCommand>
        <Label>Database Disconnect</Label>
        <Description>Disconnect from the database</Description>
        <Keyin>DBCONMGR DISCONNECT</Keyin>
        <Icon Type="NamedIcon">
            <NamedIcon>Database-Disconnect</NamedIcon>
        </Icon>
    </UserKeyinCommand>
</CommandData>
@endcode

<H3>Example <Icon> Specifications </H3>

<P>Named Ico - Ico is either in ustnicons.rsc or in a DGNLIB. </P>

@code{.unparsed}

 <Icon Type="NamedIcon">
        <NamedIcon>Circle</NamedIcon>
    </Icon>

@endcode

<P>Mdl-based IconCmd Resource from MicroStation or MDL Application. </P>

@code{.unparsed}
    <Icon Type="RscIcon">
        <RscIcon>
            <RscType>IconCmd</RscType>
            <RscId>-384</RscId>
            <TaskId>USTN</TaskId>
        </RscIcon>
    </Icon>

@endcode
<H3> <Visibility> Specification </H3>

<P>The Visibility element can contain multiple ShowExpressions and FeatureAspect elements. During a refresh event the expressions are evaluated to determine if the item should be visible. If any Show Expression returns false, the item is hidden. If the command specifies a ShowExpression it will be appended to any user defined entries. If the FeatureAspect is specified it is evaluated to determine if the item should be allowed. If the item specifies a named command (XCommand) and that command specifies a FeatureAspect then the Ribbon Component must also specify the same FeatureAspect. </P>

@code{.unparsed}

    <Visibility>
        <ShowExpression>[Session]not(Session.TreatActiveModelAs3D())</ShowExpression>
        <FeatureAspect>Surfaces_Modify</FeatureAspect>
    </Visibility>

@endcode

<H2> UI Synchronization Event System </H2>
<P>One of the major needs in adding a new UI to an existing CAD engine is keeping the UI in sync with the actual settings/parameters used by the engine. The UISyncManager has been added in MstnPlatform to satisfy this need. This manager will maintain a list of all available registered sync event types. These event types are defined in MicroStation resources and can be referenced by SyncGroupRscId and SyncItemId or by name. The name is in the format "[SyncGroupName].[SyncItemName]", for example: " ActiveLock.Snap" and "SystemEvent.ActiveModelChanged". The native DialogManager uses the UISyncManager to validate and look up available sync events. Native applications can trigger a sync event by calling the following method: </P>

@code{.unparsed} 
DialogManager::SendUISyncMessage  (UInt32 syncGroupRscId, MdlDescP mdlDesc, UInt32 syncItemId);

@endcode

<P>From a managed application a caller would use the following method.</P>

@code{.unparsed}
UMDialogManager::SendUISyncMessage (System::String^ synchItemString); 
 
@endcode

<P>When the SendUISyncMessage method is called, the message will be passed along to all ribbon components that specify interest in that event. When this occurs the ViewModel that is associated with the component will have its Refresh method called. The Refresh method will reevaluate any visibility or enable expression that are defined for the components. Typically the Ribbon's XML will have a SyncItemEvent tag anytime a ShowExpression or EnableExpression is defined. In the example below, any time the active model changes sync event, the system processes the following call. </P>
<P>DialogManager::SendUISyncMessage (SYNCGROUPID_SystemEvent, NULL, SYNCITEM_SystemEvent_ActiveModelChanged); </P>
<P>This in turn tells every component that has specified interest in the ActiveModelChanged event. </P>

@code{.unparsed} 

                <SplitButtonRef Name="Mstn.Placement.CreateCurves3D" Priority="500000">
                    <SplitButtonParams Size="Small">
                        <AccessText>PU</AccessText>
                        <PopupAccessText>U</PopupAccessText>
                        <ApplicationParams>
                            <ApplicationParam>
                                <Name>MatchingKeyTipItems</Name>
                                <Value>Mstn.Placement.CreateCurves2D</Value>
                            </ApplicationParam>
                        </ApplicationParams>
                        <SyncItemEvent>SystemEvent.ActiveModelChanged</SyncItemEvent>
                        <Visibility>
                            <ShowExpression>[Session]Session.TreatActiveModelAs3D()</ShowExpression>
                            <FeatureAspect />
                        </Visibility>
                    </SplitButtonParams>
               </SplitButtonRef>

@endcode

<P>The Sync Resources are loaded into MicroStation as it starts in the function guiDialog_startupInit (mstn/mscore/gui/guidlog.cpp). <P>

<H3>Sync Group Resource Specification </H3>

<P>The following list of sync events are available for R1 of MicroStation CONNECT:</P>

@code{.unparsed}

// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_ActiveLock =
{
"ActiveLock", 
    {
    {SYNCITEM_ActiveLock_Association,                "Association"},
    {SYNCITEM_ActiveLock_Snap,                       "Snap"},
    {SYNCITEM_ActiveLock_Grid,                       "Grid"},
    {SYNCITEM_ActiveLock_Unit,                       "Unit"},
    {SYNCITEM_ActiveLock_Angle,                      "Angle"},
    {SYNCITEM_ActiveLock_Textnode,                   "Textnode"},
    {SYNCITEM_ActiveLock_Axis,                       "Axis"},
    {SYNCITEM_ActiveLock_Scale,                      "Scale"},
    {SYNCITEM_ActiveLock_GraphGroup,                 "GraphGroup"},
    {SYNCITEM_ActiveLock_Level,                      "Level"},
    {SYNCITEM_ActiveLock_FenceMode,                  "FenceMode"},
    {SYNCITEM_ActiveLock_CellStretch,                "CellStretch"},
    {SYNCITEM_ActiveLock_Construction,               "Construction"},
    {SYNCITEM_ActiveLock_Isometric,                  "Isometric"},
    {SYNCITEM_ActiveLock_Depth,                      "Depth"},
    {SYNCITEM_ActiveLock_Isoplane,                   "Isoplane"},
    {SYNCITEM_ActiveLock_UseAnnotationScale,         "UseAnnotationScale"},
    {SYNCITEM_ActiveLock_ConstructionSnap,           "ConstructionSnap"},
    {SYNCITEM_ActiveLock_ElementTemplateAssociation, "ElementTemplateAssociation"},
    {SYNCITEM_ActiveLock_AccuSnap,                   "AccuSnap"},
    }
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_SystemEvent =
{
"SystemEvent", 
    {
    {SYNCITEM_SystemEvent_ActiveModelChanged,                  "ActiveModelChanged"},
    {SYNCITEM_SystemEvent_AvailableModelsChanged,              "AvailableModelsChanged"},
    {SYNCITEM_SystemEvent_ModelPropertiesChanged,              "ModelPropertiesChanged"},
    {SYNCITEM_SystemEvent_FileClose,                           "FileClose"},
    {SYNCITEM_SystemEvent_FileOpen,                            "FileOpen"},
    {SYNCITEM_SystemEvent_ActiveViewChanged,                   "ActiveViewChanged"},
    {SYNCITEM_SystemEvent_AvailableViewsChanged,               "AvailableViewsChanged"},
    {SYNCITEM_SystemEvent_ClipboardUpdated,                    "ClipboardUpdated"},
    {SYNCITEM_SystemEvent_AvailableLevelsChanged,              "AvailableLevelsChanged"},
    {SYNCITEM_SystemEvent_PopSetStateChanged,                  "PopSetStateChanged"},
    {SYNCITEM_SystemEvent_ColorMapChanged,                     "ColorMapChanged"},
    {SYNCITEM_SystemEvent_UndoRedoFinished,                    "UndoRedoFinished"},
    {SYNCITEM_SystemEvent_UndoMarkSet,                         "UndoMarkSet"},
    {SYNCITEM_SystemEvent_InitializeUI,                        "InitializeUI"},
    {SYNCITEM_SystemEvent_SelectionSetChanged,                 "SelectionSetChanged"},
    {SYNCITEM_SystemEvent_ContextualTabSetKeyChanged,          "ContextualTabSetKeyChanged"},
    {SYNCITEM_SystemEvent_TableCellSelectionChanged,           "TableCellSelectionChanged"},
    {SYNCITEM_SystemEvent_LuxologyRenderStateChanged,          "LuxologyRenderStateChanged"},
    {SYNCITEM_SystemEvent_ApplicationSyncUIItem,               "ApplicationSyncUIItem"},
    {SYNCITEM_SystemEvent_AnimationPreviewStateChanged,        "AnimationPreviewStateChanged"},
    {SYNCITEM_SystemEvent_DgnHistoryStateChange,               "DgnHistoryStateChange"},
    {SYNCITEM_SystemEvent_AvailableLineStylesChanged,          "AvailableLineStylesChanged"},
    {SYNCITEM_SystemEvent_ImmediateLineStylesRefreshRequired,  "ImmediateLineStylesRefreshRequired"},
    {SYNCITEM_SystemEvent_ACSOperationProcessed,               "ACSOperationProcessed"},
    {SYNCITEM_SystemEvent_RefreshAvailableViewGroupList,       "RefreshAvailableViewGroupList"},
    {SYNCITEM_SystemEvent_ViewGroupHistoryStateChange,         "ViewGroupHistoryStateChange"},
    {SYNCITEM_SystemEvent_ContextualTabActivated,              "ContextualTabActivated"},
    {SYNCITEM_SystemEvent_UserSigninStateChanged,              "UserSigninStateChanged"},
    }
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_SessionEvent =
{
"SessionEvent", 
    {
    {SYNCITEM_SessionEvent_BeforeProjectChange,              "BeforeProjectChange"},
    {SYNCITEM_SessionEvent_AfterProjectChange,               "AfterProjectChange"},
    {SYNCITEM_SessionEvent_RibbonDefinitionCfgVarChanged,    "RibbonDefinitionCfgVarChanged"},
    {SYNCITEM_SessionEvent_RibbonTabActivated,               "RibbonTabActivated"},
    {SYNCITEM_SessionEvent_RibbonQATToolListChanged,         "RibbonQATToolListChanged"},
    {SYNCITEM_SessionEvent_RibbonWorkflowChanged,            "RibbonWorkflowChanged"},
    }                           
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_CustomizationChanged =
{
"CustomizationChanged",
    {
    {SYNCITEM_CustomizationChanged_AvailableTasksChanged,               "AvailableTasksChanged"},
    {SYNCITEM_CustomizationChanged_AvailableMainTasksChanged,           "AvailableMainTasksChanged"},
    {SYNCITEM_CustomizationChanged_AvailableNameToolboxesChanged,       "AvailableNamedToolboxesChanged"},
    {SYNCITEM_CustomizationChanged_AvailableElementTemplatesChanged,    "AvailableElementTemplatesChanged"},
    {SYNCITEM_CustomizationChanged_KeyboardShortcutsChanged,            "KeyboardShortcutsChanged"},
    {SYNCITEM_CustomizationChanged_TaskNavigationTaskChanged,           "TaskNavigationTaskChanged"},
    {SYNCITEM_CustomizationChanged_AvailableColorBookColorsChanged,     "AvailableColorBookColorsChanged"},
    }
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_SymbologyChanged =
{
"SymbologyChanged", 
    {
    {SYNCITEM_SymbologyChanged_AreaMode,             "AreaMode"},
    {SYNCITEM_SymbologyChanged_CapMode,              "CapMode"},
    {SYNCITEM_SymbologyChanged_Color,                "Color"},
    {SYNCITEM_SymbologyChanged_LineWeight,           "LineWeight"},
    {SYNCITEM_SymbologyChanged_Level,                "Level"},
    {SYNCITEM_SymbologyChanged_Class,                "Class"},
    {SYNCITEM_SymbologyChanged_FillMode,             "FillMode"},
    {SYNCITEM_SymbologyChanged_FillColor,            "FillColor"},
    {SYNCITEM_SymbologyChanged_LineStyle,            "LineStyle"},
    {SYNCITEM_SymbologyChanged_DisplayPriority,      "DisplayPriority"},
    {SYNCITEM_SymbologyChanged_CellName,             "CellName"},
    {SYNCITEM_SymbologyChanged_Terminator,           "Terminator"},
    {SYNCITEM_SymbologyChanged_Point,                "Point"},
    {SYNCITEM_SymbologyChanged_PatternCell,          "PatternCell"},
    {SYNCITEM_SymbologyChanged_PatternDelta,         "PatternDelta"},
    {SYNCITEM_SymbologyChanged_PatternAngle,         "PatternAngle"},
    {SYNCITEM_SymbologyChanged_Scale,                "Scale"},
    {SYNCITEM_SymbologyChanged_AreaPatternDelta,     "AreaPatternDelta"},
    {SYNCITEM_SymbologyChanged_AreaPatternAngle,     "AreaPatternAngle"},
    {SYNCITEM_SymbologyChanged_PatternScale,         "PatternScale"},
    {SYNCITEM_SymbologyChanged_TerminatorScale,      "TerminatorScale"},
    {SYNCITEM_SymbologyChanged_Transparency,         "Transparency"},
    {SYNCITEM_SymbologyChanged_Angle,                "Angle"},
    {SYNCITEM_SymbologyChanged_LineStyleParams,      "LineStyleParams"},
    {SYNCITEM_SymbologyChanged_ElementTemplate,      "ElementTemplate"},
    }
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_ActiveParamChanged =
{
"ActiveParamChanged", 
    {
    {SYNCITEM_ActiveParamChanged_GridMode,              "GridMode"},           
    {SYNCITEM_ActiveParamChanged_ScaleDimValues,        "ScaleDimValues"},     
    {SYNCITEM_ActiveParamChanged_ScaleAnnotations,      "ScaleAnnotations"},   
    {SYNCITEM_ActiveParamChanged_ScaleMlineOffsets,     "ScaleMlineOffsets"},  
    {SYNCITEM_ActiveParamChanged_GridRef,               "GridRef"},            
    {SYNCITEM_ActiveParamChanged_TagIncrement,          "TagIncrement"},       
    {SYNCITEM_ActiveParamChanged_KeyPoint,              "KeyPoint"},           
    {SYNCITEM_ActiveParamChanged_SnapOverride,          "SnapOverride"},       
    {SYNCITEM_ActiveParamChanged_Nextggroup,            "Nextggroup"},         
    {SYNCITEM_ActiveParamChanged_Numscreens,            "Numscreens"},         
    {SYNCITEM_ActiveParamChanged_Fence,                 "Fence"},              
    {SYNCITEM_ActiveParamChanged_FenceView,             "FenceView"},          
    {SYNCITEM_ActiveParamChanged_GridOrientation,       "GridOrientation"},    
    {SYNCITEM_ActiveParamChanged_SnapMode,              "SnapMode"},           
    {SYNCITEM_ActiveParamChanged_CelllibFilename,       "CelllibFilename"},    
    {SYNCITEM_ActiveParamChanged_LevelFilter,           "LevelFilter"},       
    {SYNCITEM_ActiveParamChanged_GridUnits,             "GridUnits"},          
    {SYNCITEM_ActiveParamChanged_UnitRoundoff,          "UnitRoundoff"},       
    {SYNCITEM_ActiveParamChanged_StreamDelta,           "StreamDelta"},        
    {SYNCITEM_ActiveParamChanged_StreamTolerance,       "StreamTolerance"},    
    {SYNCITEM_ActiveParamChanged_StreamAngle,           "StreamAngle"},        
    {SYNCITEM_ActiveParamChanged_StreamArea,            "StreamArea"},         
    {SYNCITEM_ActiveParamChanged_AxisAngle,             "AxisAngle"},          
    {SYNCITEM_ActiveParamChanged_AxisOrigin,            "AxisOrigin"},         
    {SYNCITEM_ActiveParamChanged_GridAngle,             "GridAngle"}, 
    {SYNCITEM_ActiveParamChanged_DimCompat,             "DimCompatibility"}, 
    {SYNCITEM_ActiveParamChanged_MlineCompat,           "MlineCompatibility"}, 
    {SYNCITEM_ActiveParamChanged_LevelUsage,            "LevelUsage"}, 
    }
};
// Maximum of 32 SyncItems per group
SyncGroupRsc      SYNCGROUPID_ModelParamChanged =
{
"ModelParamChanged", 
    {
    {SYNCITEM_ModelParamChanged_UnitRoundRatio,         "UnitRoundRatio"},   
    {SYNCITEM_ModelParamChanged_SubPerMaster,           "SubPerMaster"},     
    {SYNCITEM_ModelParamChanged_UorPerSub,              "UorPerSub"},        
    {SYNCITEM_ModelParamChanged_MasterUnitLabel,        "MasterUnitLabel"},  
    {SYNCITEM_ModelParamChanged_SubUnitLabel,           "SubUnitLabel"},     
    {SYNCITEM_ModelParamChanged_UorPerMaster,           "UorPerMaster"},     
    {SYNCITEM_ModelParamChanged_GlobalOrigin,           "GlobalOrigin"},     
    {SYNCITEM_ModelParamChanged_GridRatio,              "GridRatio"},        
    }
};
SyncGroupRsc      SYNCGROUPID_TextParamChanged =
{
"TextParamChanged", 
    {
    {SYNCITEM_TextParamChanged_Font,                "Font"},         
    {SYNCITEM_TextParamChanged_TextJust,            "TextJust"},     
    {SYNCITEM_TextParamChanged_NodeJust,            "NodeJust"},     
    {SYNCITEM_TextParamChanged_LineLength,          "LineLength"},   
    {SYNCITEM_TextParamChanged_Tab,                 "Tab"},          
    {SYNCITEM_TextParamChanged_NextTextnode,        "NextTextnode"}, 
    {SYNCITEM_TextParamChanged_FontName,            "FontName"},     
    {SYNCITEM_TextParamChanged_TextStyle,           "TextStyle"},    
    {SYNCITEM_TextParamChanged_TextHeight,          "TextHeight"},   
    {SYNCITEM_TextParamChanged_TextWidth,           "TextWidth"},    
    {SYNCITEM_TextParamChanged_LineSpacing,         "LineSpacing"},  
    {SYNCITEM_TextParamChanged_TextSlant,           "TextSlant"},    
    }
};

@endcode

<H3>Using Sync Events in your WPF ViewModels</H3>  
<P>Example of a ViewModel that is interested in monitoring ActiveModelChanges in MicroStation. </P>

@code{.unparsed}
internal class ExampleViewModel : Bentley.MstnPlatformNET.Ribbon.ViewModels.RibbonItemViewModel        
{        
UISyncInterest                         m_ActiveModelChangedInterests;    
public ExampleViewModel()            
    {            
    UISyncInterestList refreshMasks = new UISyncInterestList ();            
    refreshMasks.AddSyncInterest (m_ActiveModelChangedInterests  = UMDialogManager.GetSyncInterest ("SystemEvent.ActiveModelChanged"));
    SyncInterestList = refreshMasks; 
    } 
 
public override void            OnUserInterfaceSyncEvent (System.UInt32[] eventMasks) 
    {   
    if (m_ActiveModelChangedInterests.IsSpecifiedInEventMasks (eventMasks))      
        Refresh();    
    }  
public override void Refresh ()    
    {      
    if (null != VisibilitySpec)           
        Visibility = VisibilitySpec.IsVisible () ? System.Windows.Visibility.Visible : System.Windows.Visibility.Collapsed;
    else          
        Visibility = System.Windows.Visibility.Visible;       
    if (this is ISupportsEnableExpression)          
        {
        ISupportsEnableExpression supportsEnableExpression = this as ISupportsEnableExpression;
        if (!String.IsNullOrWhiteSpace (supportsEnableExpression.EnableExpression))              
            IsEnabled = Bentley.Internal.MstnPlatformNET.NamedExpressionManager.EvaluateAsCriteria (supportsEnableExpression.EnableExpression, null, false); 
        } 
    }
}

@endcode

<H3>Application Provided Sync Group Resources </H3>
<P>Applications that want to add their own sync events can do so. The steps involved are the following:</P>

<OL> <LI>Create a .r file that defines your own SyncGroupRsc. If your application contains a cmd.r file you can simply add the SyncGroupRsc in the same .r file. </LI>
         <LI>Ensure the application containing the SyncGroupRsc is specified in the configuration variable MS_SYNCGROUP_APPS so the resource is loaded prior to the Ribbon. An easy way to do this is by using the <LoadConfig> tag in the part building the application. See the example part definition below.</LI>

@code{.unparsed}

  <Part Name="myapp" BMakeFile="apps\myapp.mke">
       <Bindings>
           <Files ProductDirectoryName="MdlsysAsneeded">
              Delivery\myapp.ma
               <TransKit SourceDirectory="Delivery\TransKit\MdlApps\myapp" />
               <LoadConfig AppName="myapp" ConfigVars="MS_CMDTABLE_LOAD,MS_SYNCGROUP_APPS" />
          </Files>
      </Bindings>
 </Part>
 
@endcode

         <Li>See test application ..\MstnPlatform\mstn\testapps\RibbonTestApp for example of setting up and firing Application provided Sync Events. </LI>
         
</OL>

<H3>ContextualTabSet definition </H3>

<P>The following shows two example definitions. The first shows a TabSet to activate when a single element type is selected. The second definition shows how to set up a contextual tab to activate or deactivate used API calls. This second type of activation would allow placement or edit tools to display contextual tabs. </P>

@code{.unparsed}


    <ContextualTabSets>
        <!?Example that activates/deactivates a contextual tab based on the selected element -->
        <ContextualTabSet Name="Mstn.TabSet.Table" Color="Coral" SelectFirstTabOnActivation="false">
            <Label>Table Tools</Label>
            <TabSetParams>
                <SyncItemEvent>SystemEvent.SelectionSetChanged</SyncItemEvent>
                <Visibility>
                    <ShowExpression>[Selection](Selection.ContainsSingleElement() AND Selection.ContainsText() AND Selection.OnlyContainsActiveModelElements())</ShowExpression>
                    <FeatureAspect></FeatureAspect>
                </Visibility>
            </TabSetParams>
            <ContextualTabs>
                <TabRef Name="DrawingTasks" Priority="10">
                    <TabParams>
                        <AccessText>TD</AccessText>
                    </TabParams>
                </TabRef>
            </ContextualTabs>
        </ContextualTabSet>
        
        <!?Example that activates/deactivates a contextual tab based on a key. This would be useful during tool processing -->
        <ContextualTabSet Name="Mstn.Context.Drawing" Color="Coral" SelectFirstTabOnActivation="false">
            <Label>Drawing Tools</Label>
            <TabSetParams>
                <SyncItemEvent>SystemEvent.ContextualTabKeyChanged</SyncItemEvent>
                <Visibility>
                    <ShowExpression>[Session](Session.IsContextualTabKeyActive("DrawingTest"))</ShowExpression>
                    <FeatureAspect></FeatureAspect>
                </Visibility>
            </TabSetParams>
            <ContextualTabs>
                <TabRef Name="DrawingTasks" Priority="10">
                    <TabParams>
                        <AccessText>TD</AccessText>
                    </TabParams>
                </TabRef>
            </ContextualTabs>
        </ContextualTabSet>
    </ContextualTabSets>

@endcode

<P><B>Native API</B> - The following native calls will add or remove keys into a vector of active ContextualTabSet keys. It then triggers the ContextualTabKeyChanged synch event. </P>

<UL> <LI>The following native calls will add or remove keys into a vector of active ContextualTabSet keys. It then triggers the ContextualTabKeyChanged synch event.</LI>
         <LI>DialogManager::DeactivateContextualTabSet (WCharCP key).</LI>
         <LI>DialogManager::ClearAllContextualTabSetKeys () </LI>
</UL>

<P><B>Managed API</B> - wrapper around native methods shown above. </P>

<UL> <LI>ActivateContextualTabSet (string key);</LI>
         <LI>DeactivateContextualTabSet (string key);</LI>
         <LI>ClearAllContextualTabSetKeys (); </LI>
</UL>    
<H2>Telerik RadRibbonView</H2>
<H3>RadRibbonView Features </H3>

<P>The RadRibbonView control has these key features: </P>

<UL>
<LI>MS Office 2010 Interface </LI>
<LI>Automatic Resizing & Minimization </LI>
<LI>Tabs, Groups, Galleries, Popups, Dialog Launcher </LI>
<LI>Backstage Menu & Application Menu </LI>
<LI>Buttons - Combo, Split, DropDown, Radio, Toggle </LI>
<LI>Screen Tips </LI>
<LI>Key Tips </LI>
<LI>Styling and Appearance </LI>
<LI>Expression Blend Support </LI>
</UL>

<H3>More Ribbon Related Controls </H3>

<P>The "RadControls for WPF" suite contains several class related to the Ribbon: </P>

<UL>
<LI>RadRibbonWindow </LI>
<LI>RadRibbonView </LI>
<LI>Classes with the RadRibbon prefix 
<UL><LI>Tab </Li>
        <LI>Group </LI>
        <LI>Gallery </LI>
        <LI>Button </LI>
        <LI>ComboBox </LI>
        <LI>DropDownButton </LI>
        <LI>SplitButton </LI>
        <LI>RadioButton </LI>
        <LI>ToggleButton </LI></UL>
</LI>
<Li>Other Classes used with the Ribbon 
<UL><LI>ApplicationMenu </LI>
        <LI>QuickAccessToolbar </LI>
        <LI>StackPanel </LI>
        <LI>Separator </LI></UL>
</LI>
<LI>Layout Classes for the Ribbon 
<UL><LI>RadOrderedWrapPanel </LI>
        <LI>RadCollapsiblePanel </LI></UL>
</LI>
<LI>RadRibbonBar (deprecated) - superseded by RadRibbonView </LI>
</UL>

<H3>Ribbon Events </H3>

<UL>
<LI>RadRibbonView 
<UL><LI>ApplicationButtonDoubleClick </LI>
        <LI>ApplicationMenuOpenStateChanged </LI>
        <LI>ToolBarPositionChanged </LI>
        <LI>HelpRequested </LI>
        <LI>CollapsedChanged </LI></UL>
</LI>
<LI>Selection 
<UL><LI>PreviewSelectionChanged </LI>
        <LI>SelectionChanged </LI></UL>
</LI>
<LI> Minimization 
<UL><LI>MinimizedChanged</LI>
        <LI>MinimizedPopupOpenStateChanged </LI>
        <LI>PreviewPopupOpened </LI>
        <LI>PopupOpened </LI></UL>
</LI>
<LI>RadGallery 
<UL><LI>ActionPreview </LI>
        <LI>DeactivatePreview </LI></UL>
</LI>
<LI>RadRibbonGroup 
<UL><LI>LauchDialog </LI></UL>
</LI>
</UL>

<P>You can find more information about the Telerik RadRibbonView at the <a HREF="http://www.telerik.com/help/wpf/radribbonview-overview.html"> Telerik Page</a>.</P>





@addtogroup CommandFrameworkAndXCommands

@note XCommands are Cross-UI-Platform Command definitions that can be used by the Ribbon, Menus and XCmdButtons. 

<P>User Interface Development Index: BSWUserInterfaceDevelopment

<H2>Legacy Command Support </H2>

<P>The Command is one of the most basic building blocks in PowerPlatform. Without Commands, you couldn't open a file, save a file, start the Element Selection tool, etc. Commands are identified by two pieces of information: 1) an ID number (64-bits) and 2) the ID/Name of the Task owning that Command. When used in context, there is an additional command parameter string, or "unparsed" string, passed to the command's function. So in effect, these 3 pieces of information together form a unique command. </P>


<H3>Command Tables</H3>

<P>For the PowerPlatform core and MDL applications, Commands are defined in a CommandTable resource in a .r file that is compiled using the Bentley Resource Compiler. For .NET AddIns, Commands are defined in XML files.</P>

<P>This is an example command definition from cmdtable.r in the PowerPlatform core: </P>

@code{.unparsed}

 #define CT_NONE                         0
 #define CT_MAIN                         1
 #define CT_DIALOG                       228
 . . . 

 CommandTable        CT_MAIN =
 {
 . . .
     {119, CT_DIALOG,      DIALOGOPEN,     TRY|IMM,     "DIALOG" },
 . . .

 CommandTable        CT_DIALOG =
 {
 . . .
     { 68, CT_NONE,        INHERIT,        NONE,        "OPENFILE",     580,  },
 . . .

@endcode

<P>In the CommandTable definition above, notice the string "DIALOG". This is used as the first part of the generated C #define identifier for the CommandNumber. 119 is in the first column and it will be used in the actual numeric CommandNumber. CT_DIALOG ID is in second column on that same line. That ID is used for a subsequent CommandTable definition, which contains an entry with the string "OPENFILE", a 68 and CT_NONE. 
68 will be used in the CommandNumber, and the CT_NONE indicates there are no more CommandTables to use when generating the CommandNumber. The following example shows how the hexidecimal represtations of the previous numbers are concatenated together to form the numeric CommandNumber.</P>

<P>Example CommandNumbers from the generated cmdlist.r.h command number header file: </P>

@code{.unparsed} 

 #define CMD_DIALOG_OPENFILE       0x7744000000000000UI64   /* DIALOGOPEN      CmdString = 580 */
@endcode

<P>Example command function setup: </P>

@code{.unparsed} 
 static void   myapp_openFile (WCharCP unparsedCP)
     {
     }
 . . .
 static MdlCommandNumber commandNumber[] =
     {
         {myapp_openFile,          CMD_DIALOG_OPENFILE },
         0
     };
 . . .
 extern "C" void MdlMain (int argc, WCharCP argv[])
     {
     mdlSystem_registerCommandNumbers (commandNumber);

@endcode

<P>To be thorough and not short change .NET AddIns, here is an example setup for AddIn commands:</P>

@code{.unparsed} 

 -- XML File --

 <?xml version="1.0" encoding="utf-8" ?>
 <KeyinTree xmlns="http://www.bentley.com/schemas/1.0/MicroStation/AddIn/KeyinTree.xsd">
     <RootKeyinTable ID="root">
         <Keyword SubtableRef="props" CommandClass="MacroCommand" CommandWord="MSGCENTER">
             <Options Required="true"/>
         </Keyword>
     </RootKeyinTable>

     <SubKeyinTables>
         <KeyinTable ID="props">
             <Keyword CommandWord="OPEN" />
             . . .
         </KeyinTable>
     </SubKeyinTables>

     <KeyinHandlers>
         <KeyinHandler Keyin="MSGCENTER OPEN"  Function="MsgCenter.MessageCenterApp.Open" />
         . . .
     </KeyinHandlers>
 </KeyinTree>

 -- C# File --

 namespace MsgCenter
     {
     [Bentley.MstnPlatformNET.AddInAttribute(MdlTaskID = "MsgCenter")]
     public sealed class MessageCenterApp : Bentley.MstnPlatformNET.AddIn
         {
     . . .
         /*------------------------------------------------------------------------------------**/
         /*--------------+---------------+---------------+---------------+---------------+------*/
         public static void Open
         (
         string unparsed
         )
             {
             MainWindow.OpenWindow();
             }
@endcode

<H3>IconCmds and Menus</H3>

<P>IconCmds and Menus are two types of "entry points" that activate commands using CommandNumbers. IconCmds are actually made up of 3 separate resources. They contain the following: </P>

<UL> <LI>CommandNumber </LI>
         <LI>Task ID </LI>
         <LI>Unparsed string containing command parameters </LI>
         <LI>Attributes</LI> 
         <LI>Balloon (tooltip) text</LI> 
         <LI>Flyover text, which is more descriptive than the tooltip text and is displayed in the Status Bar on hover</LI> 
         <LI>Small and Large icon information</LI> 
</UL>

<P>An example of an IconCmd using the CMD_DIALOG_OPENFILE CommandNumber: </P>

@code{.unparsed}
 DItem_IconCmdRsc ICONCMDID_OpenFile =
    {
    NOHELP, MHELPTASKIDCMD, 0,
    CMD_DIALOG_OPENFILE, MTASKID, "",
    ""
    }
    extendedAttributes
    {{
    {EXTATTR_FLYTEXT, TXT_Flyover_OpenFile},
    {EXTATTR_BALLOON, TXT_Balloon_OpenFile}
    }};

 IconCmdSmallRsc ICONCMDID_OpenFile =
    {
    24,    24,    ICONFORMAT_WINDOWS,    BLACK_INDEX, "Open File", "FileOpen"
    };

 IconCmdLargeRsc ICONCMDID_OpenFile =
    {
    32,    32,    ICONFORMAT_WINDOWS,    BLACK_INDEX, "Open File", "FileOpen"
    };

@endcode

<P>Menu items contain information similar to IconCmds, but with a few additions: </P>

<UL><LI>Label </LI>
        <LI>Accelerator key combination</LI> 
        <LI>Hook information </LI>
        <LI>Search Id </LI>
        <LI>CommandNumber </LI>
        <LI>Task Id</LI> 
        <LI>Unparsed string containing command parameters </LI>
        <LI>A reference to an IconCmd to get the icon information</LI> 

</UL>

<P>In addition, a Feature Aspect ID check can surround the menu item definition to include or exclude the menu item for Power Products. </P>

<P>An example of a menu item using the CMD_DIALOG_OPENFILE CommandNumber: </P>

@code{.unparsed}

 @if (FeatureAspect (PP_ID_FeatureAspects_File_Open))                        // @fadoc  File | Open menu item
 {TXT2_FileOpenOption,      'O'|VBIT_CTRL, ON, NOMARK, 0, NOSUBMENU,
                            HELPID_PULLDOWN_FileOpen, MHELPTASKIDTOPIC,
                            NOHOOK, MENUSEARCHID_File_Open,
                            CMD_DIALOG_OPENFILE, MTASKID, "",
                            ICONCMDID_OpenFile, Icon, MTASKID},
 @endif

@endcode

<P>In CONNECT edition, the Ribbon interface has been introduced. We're using the Telerik WPF RadRibbonView as the implementation of the ribbon control. To activate commands from the ribbon, we needed a new .NET-friendly way to get to PowerPlatform command information. IconCmds and Menu items already had duplicate information, and Ribbon Buttons would also need that same information. Instead of gathering the information from those existing resources, we decided to create a new resource that consolidates the duplicate information. The identifier for the new common resource is a name string. This new resource is called an XCommand because it's a common way of defining Cross-UI-Platform command information. The information includes: </P>

<UL><LI>Name / Id </LI>
        <LI>CommandNumber </LI>
        <LI>Task ID </LI>
        <LI>Unparsed string containing command parameters </LI>
        <LI>Icon </LI>
        <LI>Title / Label </LI>
        <LI>Description </LI>
        <LI>Feature Tracking Id (cross-referenced to Help Id)</LI> 
        <LI>Show/Hide Expression </LI>
        <LI>Enable/Disable Expression </LI>
        <LI>Toggle Expression </LI>
        <LI>Menu Mark Expression </LI>
        <LI>Accelerator </LI>
        <LI>Feature Aspect Id </LI>
</UL>

<P>The "Name / Id" is used to uniquely identify the XCommand and is used throughout PowerPlatform. Multiple XCommands are listed in a XCommandListRsc, which can be in core or in an application. The XCommands are quickly loaded during PowerPlatform 's start up and are cached. </P>

<P>The XCommand structures in dialogbox.r.h: </P>

@code{.unparsed}

 typedef struct xcommandrsc
    {
    char            name[];                
    CommandRsc      command;
    char            iconName[];
    Utf8Char        title[];
    Utf8Char        description[];
    char            featureTrackingId[];   
    char            showExpression[];      
    char            enableExpression[];    
    char            toggleExpression[];    
    char            markExpression[];
    char            uiSynchEvents[];
    UInt32          accelerator;
    UInt32          featureAspectId;
    } XCommandRsc;

 typedef struct commandrsc
    {
    CommandNumber   commandNumber;
    char            commandTaskId[];        
    char            unparsed[];             
    } CommandRsc;

@endcode

<P>An example XCommand Name is "Mstn.File.Open". "Mstn.File.Open" is given the CommandNumber of CMD_DIALOG_OPENFILE from the "Ustn" task (MTASKID), which opens the file open dialog. The following is an example of an XCommand in a .r file: </P>

@code{.unparsed}

 XCommandListRsc      XCMDLISTID_MstnPlatform =
 {
    {
 . . .
    {"Mstn.File.Open",           // File Open Dialog
        {CMD_DIALOG_OPENFILE, MTASKID, ""}, 
        "Open", 
        TXT_Balloon_OpenFile,
        TXT_Flyover_OpenFile, 
        "ec375142-3726-11e3-bf6e-6894231a2840", 
        "", "", "", "", "",
        'O'|VBIT_CTRL, 
        PP_ID_FeatureAspects_File_Open},     // @fadoc  Mstn.File.Open XCommand
 . . .
    }
 };

@endcode
@note The Feature Tracking Id is a GUID and must be unique. 

<H3>XCmdButton</H3>
<P>The XCmdButton item is similar to an IconCmd or IconCmdX, which adds an item hook capability, but the XCmdButton refers to an XCommand. In a ToolBox or DialogItemList, use the XCmdButton item type instead of IconCmd. </P>

<P>The XCmdButton structures in dlogbox.r.h: </P>

@code{.unparsed}

 typedef struct ditem_xcmdbuttonrsc
    char            xCommandName[];
    long            itemHookId;
    UInt64          itemHookArg;
    UInt32          attributes;          
    } DItem_XCmdButtonRsc;
@endcode

<P>An example of an XCmdButton in a .r file: </P>

@code{.unparsed}

 // Definition --
 DItem_XCmdButtonRsc     ICONCMDID_OpenFile =
    {
    "Mstn.File.Open", 0, 0, 0
    };

 // Reference --
 {{ 0, 0, 0, 0}, XCmdButton, ICONCMDID_OpenFile,         ON, 0, "", ""},

@endcode

<H3>PartFile and MS_XCOMMAND_APPS </H3>

<P>Any application that contains XCommand resources should add itself to the MS_XCOMMAND_APPS configuration variable, which goes in the applicationload.cfg configuration file. This is accomplished by adding an entry into the <Part> for the application in its PartFile. The specific entry goes in this element hierarchy: <Part>, <Bindings>, <Files>, <LoadConfig>, ConfigVars ="...,MS_XCOMMAND_APPS" attribute. </P>

<P>An example of including MX_XCOMMAND_APPS in the ConfigVars attribute of the <LoadConfig> element: </P>

@code{.unparsed}

 <Part Name="MdlApp-2ddraw" BMakeFile="apps\2ddraw\2ddraw.mke">
     <SubPart PartName="2dModelingDll" />
     <Bindings>
         <Files ProductDirectoryName="MdlsysAsneeded" FeatureAspect="PP_ID_FeatureAspects_BaseGeometry">
             Delivery\2ddraw.ma
             <TransKit SourceDirectory="Delivery\TransKit\MdlApps\2dModeling\2ddraw" />
             <LoadConfig AppName="2ddraw" ConfigVars="MS_CMDTABLE_LOAD,MS_XCOMMAND_APPS" />
         </Files>
     </Bindings>
 </Part>

@endcode

<H3>Native API </H3>

<P>The native API for XCommands is in the following interface and classes: </P>

<UL><LI>IXCommand - native interface for Cross UI Framework PowerPlatform Command </LI>
        <LI>XCommand - native class and implementation of IXCommand </LI>
        <LI>XCommandManager - manager and caching class for XCommands</LI> 
</UL>

<P>The following is an example of using the native XCommand API to activate/execute a command: </P>

@code{.unparsed}

 #include    <Mstn\XCommand.h>
 #include    <Mstn\XCommandManager.h>
 . . .
 IXCommandP   xCommandP;

 xCommandP = XCommandManager::GetManager().FindXCommand (L"Mstn.File.Open");

 if (NULL != xCommandP)
     xCommand->ExecuteCmd (NULL, NULL);

@endcode

<H2>The Ribbon and XCommands </H2>

<P>The PowerPlatform Ribbon uses the RadRibbonView from Telerik and is WPF based. Any discussion of WPF commands starts with an introduction to Microsoft's ICommand interface. </P>

<H3>ICommand and RelayCommand </H3>

<P>ICommand is in the System.Windows.Input namespace. It is in PresentationCore.dll in .NET 4 and earlier and in System.dll starting with .NET 4.5. ICommand contains the CanExecute and Execute methods and the CanExecuteChanged event. The CanExecute method controls whether a WPF button or menu item is enabled or disabled. The Execute method fires off the method associated with the command. The CanExecuteChanged event is fired when changes occur that affect whether or not the command can execute.<a href="http://msdn.microsoft.com/en-us/library/system.windows.input.icommand(v=vs.110).aspx">ICommand Interface</a>.</P>

<P>The RelayCommand class in Bentley.UI.Mvvm is an implementation of the ICommand interface. The RelayCommand 's sole purpose is to relay its functionality to another object by invoking delegates. Our RelayCommand implementation came from Josh Smith's library of MVVM classes. </P>

<H3>IMstnCommand and NamedMstnCommand </H3>

<P>The IMstnCommand interface is a managed interface for PowerPlatform commands. IMstnCommand is UI technology neutral. IMstnCommand, and several of its implementations, are in the MstnPlatformNET.Commands namespace in MicroStation.dll. IMstnCommand contains these properties: </P>

<UL><LI>bool CanExecute</LI>
        <LI>bool CanDisplay </LI>
        <LI>String IconName </LI>
        <LI>BMG::RscIconSpec IconSpec </LI>
        <LI>String Label </LI> 
        <LI>String Description </LI>
        <LI>String AcceleratorString </LI>
</UL>

<P>The CanExecute property is all that overlaps with something in the ICommand interface. Everything else is unique to PowerPlatform. The MstnCommand class is an abstract base class that adds Named Expressions for Show, Enable, Toggle and Menu Mark. The NamedMstnCommand class is a subclass of MstnCommand and is the managed wrapper around the native XCommand. </P>

<H3>MstnRelayCommand </H3>

<P>The MstnRelayCommand class is a subclass of RelayCommand. It is WPF specific and is in the Bentley.MicroStation.WPF.dll assembly. It forms the connection between the Microsoft ICommand interface and the Bentley IMstnCommand interface introduced above. MstnRelayCommand contains: </P>

<UL><LI>MstnRelayCommand ( BM.Commands.IMstnCommand)</LI> 
        <LI>bool CanDisplay </LI>
        <LI>SW.Visibility Visibility</LI> 
        <LI>ImageSource SmallImage </LI>
        <LI>ImageSource LargeImage </LI>
        <LI>String Label </LI>
        <LI>String Description </LI>
        <LI>String AcceleratorString</LI> 
        <LI>BMC::IMstnCommand Command </LI>
        <LI>bool CanExecute () (from ICommand)</LI> 
        <LI>Execute() (from ICommand)</LI> 
        <LI>CanExecuteChanged event (from ICommand)</LI> 
</UL>

<H3>Ribbon Definitions </H3>

<P>To include anything in the PowerPlatform ribbon, it needs to be defined in a "Ribbon Definition". Ribbon Definitions are specified in an XML file conforming to the RibbonDefinitions.xsd file. There are definitions for numerous objects making up the ribbon, including Buttons, DropDownButtons, SplitButtons, Groups, Tabs, etc. Buttons, DropDownButtons, SplitButtons definitions may contain "Command Data" that refers to a "Named Command", which is really a reference to a NamedMstnCommand instance. </P>

<P>An example of a <Button> element in an XML file: </P>

@code{.unparsed}

    <Buttons>
        <Button Name="Mstn.File.Open" Priority="0">
            <ButtonData>
                <CommandData Type="NamedCommand">
                    <NamedCommand>Mstn.File.Open</NamedCommand>
                </CommandData>
            </ButtonData>
        </Button>
        . . .
    </Buttons>

@endcode

<P>An example of a <ButtonRef> element referring to a Named <Button> in an XML file: </P>

@code{.unparsed}

 <QuickAccessCollections>
     <QuickAccessCollection Name="Mstn.QuickAccessItems" . . .

         <ButtonRef Name="Mstn.File.Open"  Priority="5">
             <ButtonParams Size="Small" CollapseToSmall="Never" CollapseToMedium="Never">
                 <AccessText>2</AccessText>
             </ButtonParams>
         </ButtonRef>
 . . .
@endcode

<H3>Using NamedMstnCommands and MstnRelayCommands in C# and XAML </H3>

<P>An example of exposing an XCommand to C# or XAML via the NamedMstnCommand and MstnRelayCommand classes: </P>

@code{.unparsed}
 -- MyCommands.cs --

 using BM = Bentley.MstnPlatformNET;

 class MyCommands
     {
     private MstnRelayCommand m_FileOpen;
     public MstnRelayCommand FileOpen
         {
         get
             {
             if (m_FileOpen == null)
                 m_FileOpen = new MstnRelayCommand(new BM.Commands.NamedMstnCommand ("Mstn.File.Open"));
             return m_FileOpen;
             }
         }

 -- MyViewModel.cs --

    public MyCommands MyCommands;

@endcode

<P>An example of referencing an MstnRelayCommand in XAML for the Backstage: </P>

@code{.unparsed}
 -- MyView.xaml --

 xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"

 <telerik:RadRibbonBackstageItem Header="{x:Static props:Resources.Open_Label}"
                                 IsSelectable="False"
                                 CloseOnClick="True"
                                 Command="{Binding MyCommands.FileOpen}"
                                 Visibility="{Binding MyCommands.FileOpen.Visibility}"
                                 telerik:KeyTipService.AccessText="O"/>


@endcode

<H3>XCommands for .NET AddIns </H3>

<P>We have implemented a way for managed applications to supply XCommandRsc ’s using a Bentley resource manager resource (.r) file. Here are the steps for using this capability. </P>

<OL>
<LI><B>Create resource file containing an XCommandRscList with the same name as your managed assembly.</B>For example, if your assembly is Bentley.ECUISupport.dll, then your resource file should be Bentley.ECUISupport.r. See Bentley.ECUISupport.r for an example XCommand resource file. Here is a section of the Bentley.ECUISupport.r file: 
@code{.unparsed}

 #include <Mstn\MicroStation.r.h>
 #include <Mstn\MdlApi\dlogbox.r.h>
 
 #include <ribbontext.h>
 #include <rsrctxt2.h>
 
 #include <TransKitGenSrc\bentley.ecuisupportcmd.h>
 #include <TransKitGenSrc\PowerPlatform.FeatureAspects.h>

 XCommandListRsc      1 =
 {
     {
     {"Mstn.File.Properties", 
         {CMD_ELEMENT_INFO_FILEPROPERTIES, "Bentley.ECUISupport", ""}, 
         "Properties",
         TXT_RibbonLabel_FileProperties,
         TXT_RibbonDesc_FileProperties,
         "ec383b8d-3726-11e3-8f85-6894231a2840", "", "", "", "", "", NOACCEL, 
         PP_ID_FeatureAspects_File_Properties},                                   // @fadoc  File.Properties XCommand
     {"Mstn.ProjectNavigation.Explorer", 
         {CMD_DIALOG_EXPLORER_TOGGLE, "Bentley.ECUISupport", ""}, 
         "ProjectExplorer",
         TXT2_FileProjectOption,
         TXT_RibbonDesc_Explorer,
         "ec3a104e-3726-11e3-a7ad-6894231a2840", "", "", "", "", "", NOACCEL, 
         PP_ID_FeatureAspects_Properties_ECBrowser},                             // @fadoc  ProjectNavigation.Explorer XCommand
 
    }
 };

@endcode

<P>Note that the XCommandListRsc ’s in MicroStation ’s source files use defined constants such as “TXT_RibbonLabel_FileProperties” because those text strings are also used in other places. It is not necessary to do that (you can just put the English strings directly into the resource) because a .rsc.mui.xliff file is generated from this file for localization purposes. </P>
<P>The field following the CMD_xxx entry must be the Add-in’s TaskId. You can find out what that is by looking in the application dropdown in MicroStation ’s keyin browser. For XCommandRsc ’s added through the mechanism described here, it must be filled in. </P>
<P>The "#include <TransKitGenSrc\bentley.ecuisupportcmd.h>" and CMD_ELEMENT_INFO_FILEPROPERTIES sections are related to step 4 below.</P></LI> 

<LI><B>Modify your transkit.xml file to specify that the XCommands resource file specified above is included in your translatable resources.</B> For example, the <BentleyRsc> element was added to the ECUISupport transkit.xml file: 

@code{.unparsed}

 <?xml version="1.0" encoding="utf-8"?>

 <Transkit>

    <SatelliteAssembly DllName="Bentley.ECUISupport" DeliverEnglish="False" RightsCompliant="True">
        <ResxFile ResourceName="Bentley.ECUISupport" FileName="ECUISupport.resx" />
    </SatelliteAssembly>

    <BentleyRsc Name="Bentley.ECUISupport.rsc.mui" >
        <ResourceSource>Bentley.ECUISupport.r</ResourceSource>
    </BentleyRsc>
 </Transkit>

@endcode
</LI>

<LI><B>Modify the part in your xxx.PartFile.xml file to tell BentleyBuild that you want to deliver the compiled XCommand resource file alongside your assembly.</B> You also need to add your .rsc file to the MS_XCOMMAND_RSRCS configuration file. If you are working with a MicroStation part, that can be done in the part file. The "Delivery\Bentley.ECUISupport.rsc" and "MS_XCOMMAND_RSCS" additions were made to the Bentley.ECUISupport part in PowerPlatform.Partfile.xml: </LI>

@code{.unparsed}

    <Part Name="ClrApp-ECUISupport" BMakeFile="mstn\clrapps\ECUISupport\ECUISupport.mke">
        <SubPart PartName="DgnDisplayNet" PartFile="DgnDisplayNet" Repository="DgnDisplayNet" />
        <SubPart PartName="ClrApp-propertymanager" />
        <SubPart PartName="Componentsets" PartFile="PPModules\Componentsets\Componentsets" />
        <Bindings>
            <Assemblies ProductDirectoryName="PPManagedAssemblies">
                Delivery\Bentley.ECUISupport.dll
                Delivery\Bentley.ECUISupport.rsc
                <TransKit SourceDirectory="Delivery\TransKit\clrapps\Bentley.ECUISupport" />
                <LoadConfig AppName="Bentley.ECUISupport" ConfigVars="MS_CMDTABLE_LOAD,MS_XCOMMAND_RSCS" />
            </Assemblies>
        </Bindings>
    </Part>

@endcode

<LI><B>In your bmake file, make sure you are generating the .h file that specifies the CMD_xxx constants from your command table.</B>If you are interested in making XCommand resources, that means you have specified the command structure of your application in an xml file, usually in a file named something like <appname>.commands.xml. You need to generate an include file that defines constants that you can use in the XCommands resource. In ECUISupport.mke, this was added: 

@code{.unparsed}

 #----------------------------------------------------------------------
 # Create the command table include file.
 #----------------------------------------------------------------------
 $(gensrcTransKit)$(appName)cmd.h       : $(baseDir)src/Resources/ECUISupport.commands.xml

@endcode

<P>If you look back at Step 1, you will see where the generated header file is #included, and where the constants are used in the XCommand specification. </P>
</LI>

<LI><B>Modify your bmake file to set up processing of the BentleyRsc section of the transkit.xml file.</B> The following is in a new section that was added near the end of ECUISupport.mke. 

@code{.unparsed}

#----------------------------------------------------------------------
# Create and SymLink the XCommand .rsc file
#----------------------------------------------------------------------
MuiBaseName             = $(appName).rsc
MuiTranskitDeliveryDir  = $(ContextDeliveryDir)TransKit/clrapps/$(appName)/
MuiAdditionalIncludes   = $(MSCore)TransKit/SharedInc/ $(gensrc)
MuiTranskitSourceDir    = $(baseDir)src/Resources/

# This tells CreateAndSymLinkMui to symlink the resource file itself
ForClrAppXCommand       = 1>

# This tells CreateAndSymLinkMui to avoid symlinking the transkit.xml file - SymLinkResxTrankitFiles.py does that.
DontSymLinkTranskitXml  = 1

%include $(SharedMki)CreateAndSymlinkMui.mki

@endcode

<P>Since this new section uses only bmake variables that are usually defined in every bmake file (e.g., appName, ContextDeliveryDir, baseDir), you can pretty much copy that section. If you are not working in the MicroStation source, you probably need to change the definition of MuiAdditionalIncludes, often to just $(gensrc). In the example, $(MSCORE)Transkit/SharedInc/ is there so that ribbontext.h is found to resolve the constants like TXT_RibbonLable_FileProperties.</P>
</LI>
</OL> 
<P>If you follow the steps above, you should find the <appName>.rsc file delivered in the same directory as your <appName>.dll file. In the en subdirectory, there should be an <appName>.rsc.mui file, and an <appName>.rsc.mui.xliff file is created to be added to the transkit. </P>



@addtogroup IRibbonComponentProviders

@note IRibbonComponentProviders provide component that can be placed on the Ribbon in MicroStation 
        
<H2>IRibbonComponentProviders </H2>

<P>Managed applications can provide their own components for the Ribbon by implementing the IRibbonComponentProvider interface and registering it with the RibbonComponentManager. This interface allows application provided to properly work with standard ribbon features such as ribbon search, popup groups, and Hidden Tool resources. The following shows an example of registering a provider: </P>
        
@code{.unparsed}        
        
 RibbonComponentManager.Manager.RegisterRibbonComponentProvider (new RibbonComponentProvider ());       
        
@endcode        
        
<P>A RibbonComponent has three basic requirements. It must supply/register a definition of itself. It must create a viewmodel that will serve as a data context for actual WPF control. It must create the WPF control that will be inserted into the ribbon. </P>
<P>The definition must supply a name and that name must be unique for the component type. For example two button definitions should not have the same name. A list of the primary component types are shown below.</P>

<table>
<tr>
<th>Component Type</th> <th>Definition Type</th> <th>ViewModel Type</th> <th>Control Type</th>
</tr>
<tr>    
<td>Tab</td> <td>RibbonTabDefinition</td> <td>RibbonTabViewModel</td> <td>RadRibbonTab</td>
</tr>   
<tr>
<td>Group </td> <td>RibbonGroupDefinition </td> <td>RibbonGroupViewModel </td> <td>RadRibbonGroup</td>
</tr>
<tr>
<td>Panel </td> <td>RibbonGroupPanelDefinition </td> <td>RibbonGroupPanelViewModel </td> <td>StackPanel,RadCollapsiblePanel, or RadOrderedWrapPanel </td>
</tr>   
<tr>
<td>ButtonGroup </td> <td>RibbonButtonGroupDefinition </td> <td>RibbonButtonGroupViewModel</td> <td>RadButtonGroup </td>
</tr>
<tr>
<td>Button </td> <td>RibbonButtonDefinition </td> <td>RibbonButtonViewModel </td> <td>RadRibbonButton </td>
</tr>
<tr>
<td>DropDownButton </td> <td>RibbonDropDownButtonDefinition </td> <td> RibbonDropDownButtonViewModel </td> <td>RadRibbonDropDownButton </td>
</tr>   
<tr>
<td>SplitButton </td> <td>RibbonSplitButtonDefinition </td> <td> RibbonSplitButtonViewModel  </td> <td>RadRibbonSplitButton  </td>
</tr>   
<tr>
<td>ToggleButton </td> <td>RibbonToggleButtonDefinition </td> <td> RibbonToggleButtonViewModel </td> <td>RadRibbonToggleButton  </td>
</tr>   
<tr>
<td>RadioButton </td> <td>RibbonRadioButtonDefinition </td> <td> RibbonRadioButtonViewModel  </td> <td>RadRibbonRadioButton  </td>
</tr>   
<tr>
<td>ComboBox </td> <td>RibbonComboBoxDefinition  </td> <td> RibbonComboBoxViewModel   </td> <td>RadRibbonComboBox  </td>
</tr>   
<tr>
<td>Gallery </td> <td>RibbonGalleryDefinition   </td> <td> RibbonGalleryViewModel   </td> <td>RadRibbonGallery   </td>
</tr>   
</table>        
        
<P>The names of the definitions are used to configure the presentation of the Ribbon. To see example configurations look at the XML files in MstnPlatform \mstn\clrapps\RibbonView\RibbonXML. </P>
<P>The Bentley.MstnPlatformNET.Ribbon.IRibbonComponentProvider interface definition is shown below: </P>        
        
@code{.unparsed}
        
   public interface IRibbonComponentProvider
        {
        String ProviderKey  {get;}

        IList<RibbonTabCollectionDefinition>        RegisterTabCollectionDefinitions ();
        IList<ContextualTabSetDefinition>           RegisterContextualTabSetDefinitions ();
        IList<QuickAccessCollectionDefinition>      RegisterQuickAccessCollectionDefinitions ();
        IList<RibbonButtonGroupDefinition>          RegisterButtonGroupDefinitions ();
        IList<RibbonButtonDefinition>               RegisterButtonDefinitions ();
        IList<RibbonDropDownButtonDefinition>       RegisterDropDownButtonDefinitions ();
        IList<RibbonSplitButtonDefinition>          RegisterSplitButtonDefinitions ();
        IList<RibbonToggleButtonDefinition>         RegisterToggleButtonDefinitions ();
        IList<RibbonRadioButtonDefinition>          RegisterRadioButtonDefinitions ();
        IList<RibbonComboBoxDefinition>             RegisterComboBoxDefinitions ();
        IList<RibbonTabDefinition>                  RegisterTabDefinitions ();
        IList<RibbonMenuItemCollectionDefinition>   RegisterMenuItemCollectionDefinitions ();
        IList<RibbonGroupPanelDefinition>           RegisterGroupPanelDefinitions ();
        IList<RibbonGroupDefinition>                RegisterGroupDefinitions ();
        IList<RibbonGalleryDefinition>              RegisterGalleryDefinitions ();
        IList<WorkflowDefinition>                   RegisterWorkflowDefinitions ();
        IList<RibbonDropDownPanelDefinition>        RegisterDropDownPanelDefinitions ();
        IList<BackstageItemDefinition>              RegisterBackstageItemDefinitions ();

        ContextualTabSetViewModel                 CreateContextualTabSetViewModelFromDefinition (ContextualTabSetDefinition def);
        TabCollectionViewModel                    CreateTabCollectionViewModelFromDefinition (RibbonTabCollectionDefinition def);
        QuickAccessToolbarViewModel               CreateQuickAccessCollectioniewModelFromDefinition (QuickAccessCollectionDefinition def);
        IRibbonItemViewModel                      CreateButtonGroupViewModelFromDefinition (RibbonButtonGroupDefinition def);
        IRibbonItemViewModel                      CreateButtonViewModelFromDefinition (RibbonButtonDefinition def);
        IRibbonItemViewModel                      CreateDropDownButtonViewModelFromDefinition (RibbonDropDownButtonDefinition def);
        IRibbonItemViewModel                      CreateSplitButtonViewModelFromDefinition (RibbonSplitButtonDefinition def);
        IRibbonItemViewModel                      CreateToggleButtonViewModelFromDefinition (RibbonToggleButtonDefinition def);
        IRibbonItemViewModel                      CreateRadioButtonViewModelFromDefinition (RibbonRadioButtonDefinition def);
        IRibbonItemViewModel                      CreateComboBoxViewModelFromDefinition (RibbonComboBoxDefinition def);
        IRibbonItemViewModel                      CreateTabViewModelFromDefinition (RibbonTabDefinition def);
        RibbonMenuItemCollectionViewModel         CreateMenuItemCollectionViewModelFromDefinition (RibbonMenuItemCollectionDefinition def);
        IRibbonItemViewModel                      CreateGroupPanelViewModelFromDefinition (RibbonGroupPanelDefinition def);
        IRibbonItemViewModel                      CreateGroupViewModelFromDefinition (RibbonGroupDefinition def);
        IRibbonItemViewModel                      CreateGalleryViewModelFromDefinition (RibbonGalleryDefinition def);
        IRibbonItemViewModel                      CreateBackstageItemViewModelFromDefinition (BackstageItemDefinition def, ViewModelContext context);

        RadButtonGroup                           CreateButtonGroupFromViewModel (IRibbonItemViewModel item);
        RadRibbonButton                          CreateButtonFromViewModel (IRibbonItemViewModel item);
        RadDropDownButton                        CreateDropDownButtonFromViewModel (IRibbonItemViewModel item);
        RadRibbonSplitButton                     CreateSplitButtonFromViewModel (IRibbonItemViewModel item);
        RadRibbonToggleButton                    CreateToggleButtonFromViewModel (IRibbonItemViewModel item);
        RadRibbonRadioButton                     CreateRadioButtonFromViewModel (IRibbonItemViewModel item);
        RadRibbonComboBox                        CreateComboBoxFromViewModel (IRibbonItemViewModel item);
        RadRibbonTab                             CreateTabFromViewModel (IRibbonItemViewModel item);
        Object                                   CreatePanelFromViewModel (IRibbonItemViewModel item);
        RadRibbonGroup                           CreateGroupFromViewModel (IRibbonItemViewModel item);
        RadRibbonGallery                         CreateGalleryFromViewModel (IRibbonItemViewModel item);
        RadRibbonBackstageItem                   CreateBackstageItemFromViewModel (IRibbonItemViewModel itemVm);
        }
@endcode

<P>The class Bentley.MstnPlatformNET.Ribbon.BaseRibbonComponentProvider is provided to allow users to easily implement RibbonComponentProviders which only provide a subset of possible component types. For an example implementation of an IRibbonComponentProvider, see the file MstnPlatform \mstn\clrapps\RibbonView\RibbonComponentProvider.cs which provides Tab, DropDownButton, and ComboBox components current seen in the Ribbon. </P>

<H3>Specifying Ribbon Component Providers</H3>

<P>The variable MS_RIBBONCOMPONENTPROVIDERS is used to specify ribbon component providers. The RibbonView application will load the specified provider dll and create the class that is specified by the InstanceOnLoad attribute. </P>

<H3>Example - Setting up a component provider </H3>

@code{.unparsed}
        
     Addin Name: 
         MyComponentProvider.dll
      cfg setting:
         MS_RIBBONCOMPONENTPROVIDERS < MyComponentProvider 

   [Bentley.MstnPlatformNET.Ribbon.InstanceOnLoad]
    public class MyComponentProvider : Bentley.MstnPlatformNET.Ribbon.BaseRibbonComponentProvider
        {
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public MyComponentProvider
        (
        )
            {
            RibbonComponentManager.Manager.RegisterRibbonComponentProvider (this)
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public override string ProviderKey     
            {
             get {return "MyComponentProvider.RibbonComponentProvider"; }
             }
        
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        ~ MyComponentProvider()  // destructor
            {
            RibbonComponentManager.Manager.UnRegisterRibbonComponentProvider (this.Name)
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public override IList<RibbonDropDownButtonDefinition>       RegisterDropDownButtonDefinitions ()
            {
            ...
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public override    IRibbonItemViewModel                      CreateDropDownButtonViewModelFromDefinition (RibbonDropDownButtonDefinition def)
            {
            switch (def.Name)
                {
                case "MyDropDownItem":
                    {
                    MyIRibbonItemVeiwModelBasedViewModel vm = new ....

                    // set any specific property overrides from definition, like AccessText
                    RibbonViewModelHelper.CopyPropertiesFromDefinition (vm, def);

                    return  vm;
                    }
                }
            return null;
            }
            
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public override RadDropDownButton               CreateDropDownButtonFromViewModel (IRibbonItemViewModel itemVm)
            {
            switch (def.Name)
                {
                case "MyDropDownItem":
                    {
                    MyIRibbonItemVeiwModelBasedViewModel myVm = itemVm as MyIRibbonItemVeiwModelBasedViewModel;

                    RadDropDownButton button = new MyDropDownButton (myVm);  // button.DataContext should be set to your ViewModel (myVm)
                    
                    // set any specific overrides from definition, like AccessText and ToolTips
                    RibbonComponentHelper.SetRadDropDownButtonPropertiesFromVM(button, itemVm);

                    return  button;
                    }
                }
            return null;
            }
@endcode

<H3>Setting style to make Sure Your xaml supplied Tab, Groups and Buttons display </H3>
<P>Step 1. Ensure your addin is subclassed from WpfAddin and make sure to define a ThemStyle attribute that specifies where the style resources are located.</P>

@code{.unparsed}        
        
[Bentley.MstnPlatformNET.AddInAttribute(MdlTaskID = "TableUI")]
[ThemeStyle ("Bentley.TableUI", "Themes/Common.xaml")]
public classTableUIApp : WpfAddIn
  {     
        
@endcode
        
<P>Step 2. Define your styles in Common.xaml, below is an example.</P>

@code{.unparsed}        
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"xmlns:local="clr-namespace:Bentley.MstnPlatformNET.TableUI.Views">
<Style BasedOn="{StaticResource RadRibbonButtonStyle}" TargetType="{x:Type local:DistributeColumnsButton}"/>
<Style BasedOn="{StaticResource RadRibbonButtonStyle}" TargetType="{x:Type local:DistributeRowsButton}"/>
<Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableSymbologyGroup}"/>
<Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableOptionsGroup}"/>
<Style BasedOn="{StaticResource RadRibbonDropDownButtonStyle}" TargetType="{x:Type local:ShadingDropDownButton}"/>
<Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableColorDropDownButton}" >
 <Setter Property="DropDownHeight"Value="450" /><Setter Property="DropDownWidth"Value="500" />
</Style>
<Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableLineStyleDropDownButton}" >
 <Setter Property="DropDownHeight"Value="500" /><Setter Property="DropDownWidth"Value="180" />
</Style>
<Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableLineWeightDropDownButton}" >
 <Setter Property="DropDownHeight"Value="400" /><Setter Property="DropDownWidth"Value="170" />
</Style>
<Style BasedOn="{StaticResource RadRibbonSplitButtonStyle}" TargetType="{x:Type local:TableBordersSplitButton}"/>
<Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:CellSizeGroup}"/>
<Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableSizeGroup}"/>
  </ResourceDictionary>         
@endcode

<H3>Supporting RightClick HiddenTool Processing (and RibbonSearch support) </H3>

<P>If you want the Ribbon to see your components when it collects up a list of items to display the Show/Hide right click menu, the ViewModel set as the DataContext of your component must implement the ISupportsHidingViaUserPrefs interface and provide a non-null UniqueOccurrenceName, UniqueOccurrenceLabel, ParentOccurence, and ItemType. This Interface includes the interface ISupportUniqueOccurrence which is used to add entries into the Ribbon Search box. So if you implement ISupportsHidingViaUserPrefs your component is compatible with both features. These interfaces are also implemented in IRibbonItemViewModel. Since the RibbonComponentManager uses IRibbonItemViewModel, your viewmodels should automatically work with both features. Note, that currently only components that implement ISupportsMstnRelayCommand will be shown in Ribbon Search. </P>
<P>If your component provider is providing a RadRibbonGroup, the ViewModel that serves as the DataContext for the group must implement ISupportsRibbonItems. Each object in the "Items" collection, must have their DataContext set to an IRibbonItemViewModel or at a minimum implement ISupportsHidingViaUserPrefs. </P>

<H3>Storing State Data for Ribbon Components </H3>
        
<P>State data is data that you want to save between MicroStation design sessions. To store the state data of ribbon components into the common ribbon state file typically named "MstnRibbonState.xml" if not overridden by variable MS_RIBBONPREFS the following procedure can be followed:</P>
<OL>
<LI>Define a class to get/set your state data properties. </LI>
<LI>Define ECProperties within an ECClass that is uniquely named for your provider.</LI>
<LI>Add the ECClass to the ECSchema that is provided by Bentley.MicroStation.Ribbon.dll in the static property Bentley.MstnPlatformNET.Ribbon.RibbonState.Schema</LI>
<LI>Set up C# Properties that get and set values in the instance specific to your provider.</LI>
<LI>If a property value is changed call RibbonState.RibbonStateData.Dirty = true; to force the state file to be rewritten when the MicroStation session is closed.</LI>
        
        
<H3>Example - Defining Ribbon Component Provider State Data </H3>

The following code is an example implementate of a ViewGroupHistoryState class for the ViewGroupHistory Ribbon Component provider. This can serve as a template for other RibbonComponentProviders. </P>


@code{.unparsed}

    /*--------------------------------------------------------------------------------------+
    |
    |     $Source: docs/Articles/APIIntroductionMDL.h $
    |
    |  $Copyright: (c) 2017 Bentley Systems, Incorporated. All rights reserved. $
    |
    +--------------------------------------------------------------------------------------*/
    namespace Bentley.ViewGroupHistory
    {
    using       System;
    using       Bentley.ECObjects;
    using       Bentley.ECObjects.XML;
    using       Bentley.ECObjects.Schema;
    using       Bentley.ECObjects.Instance;
    using       System.IO;
    using       System.Xml;
    using       Bentley.DgnPlatformNET;
    using       System.Collections.Generic;
    using       Bentley.MstnPlatformNET.Ribbon;

    /*====================================================================================**/
    /*==============+===============+===============+===============+===============+======*/
    public sealed class ViewGroupHistoryState
        {
        private static ViewGroupHistoryState   s_state;

        // Name of Class to be added to the RibbonState schema. This must be unique across all RibbonComponent Providers
        private const string s_StateClassName        = @"ViewGroupHistoryState";

        // Set up const strings for all the name of all ECProperties that will be needed to hold out state data
        private const string s_propname_AllDropDownWidth = @"AllDropDownWidth";
        private const string s_propname_AllDropDownHeight = @"AllDropDownHeight";
        private const string s_propname_PreviousDropDownWidth = @"PrevDropDownWidth";
        private const string s_propname_PreviousDropDownHeight = @"PrevDropDownHeight";
        private const string s_propname_NextDropDownWidth = @"NextDropDownWidth";
        private const string s_propname_NextDropDownHeight = @"NextDropDownHeight";

        //  Private methods
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private ViewGroupHistoryState ()
            {
            // Get the default RibbonState schema and define the class the will hold the state 
            // values for the component this assemble provides.
            ECSchema schema = RibbonState.Schema;
            if (null != schema)
                LoadViewGroupHistoryStateClass (schema);
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void RegisterProperty (IECClass stateClass, string name, IECPrimitiveType type)
            {
            stateClass.Add (new ECProperty (name, type));
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void LoadViewGroupHistoryStateClass (ECSchema schema)
            {
            ECClass stateClass = new ECClass (s_StateClassName);

            RegisterProperty (stateClass, s_propname_AllDropDownWidth, ECObjects.DoubleType);
            RegisterProperty (stateClass, s_propname_AllDropDownHeight, ECObjects.DoubleType);

            RegisterProperty (stateClass, s_propname_PreviousDropDownWidth, ECObjects.DoubleType);
            RegisterProperty (stateClass, s_propname_PreviousDropDownHeight, ECObjects.DoubleType);

            RegisterProperty (stateClass, s_propname_NextDropDownWidth, ECObjects.DoubleType);
            RegisterProperty (stateClass, s_propname_NextDropDownHeight, ECObjects.DoubleType);

            schema.AddClass (stateClass);
            schema.TrimToSize ();
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private IECInstance     StateInstance
            {
            get
                {
                return RibbonState.RibbonStateData.GetOrCreateInstanceByClassName (s_StateClassName);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private string GetPropertyAsString (string name, string defaultValue="")
            {
            return ECInstanceHelper.GetInstanceStringValue (StateInstance, name, defaultValue);
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void SetPropertyString (string name, string value)
            {
            IECInstance instance = StateInstance;
            IECPropertyValue propVal = instance[name];

            if (propVal.IsNull || value != propVal.StringValue)
                {
                instance[name].StringValue = value;
                RibbonState.RibbonStateData.Dirty = true;
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private double GetPropertyAsDouble(string name, double defaultValue=0.0)
            {
            return ECInstanceHelper.GetInstanceDoubleValue (StateInstance, name, defaultValue);
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void SetPropertyDouble (string name, double value)
            {
            IECInstance instance = StateInstance;
            IECPropertyValue propVal = instance[name];

            if (propVal.IsNull || value != propVal.DoubleValue)
                {
                instance[name].DoubleValue = value;
                RibbonState.RibbonStateData.Dirty = true;
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private double GetPropertyAsInt (string name, int defaultValue=0)
            {
            return ECInstanceHelper.GetInstanceIntValue (StateInstance, name, defaultValue);
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void SetPropertyInt (string name, int value)
            {
            IECInstance instance = StateInstance;
            IECPropertyValue propVal = instance[name];

            if (propVal.IsNull || value != propVal.IntValue)
                {
                instance[name].IntValue = value;
                RibbonState.RibbonStateData.Dirty = true;
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private bool GetPropertyAsBool (string name, bool defaultValue=false)
            {
            return ECInstanceHelper.GetInstanceBoolValue (StateInstance, name, defaultValue);
            }
        
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        private void SetPropertyBool (string name, bool value)
            {
            IECInstance instance = StateInstance;
            IECPropertyValue propVal = instance[name];

            if (propVal.IsNull || value != (bool)propVal.NativeValue)
                {
                instance[name].NativeValue = value;
                RibbonState.RibbonStateData.Dirty = true;
                }
            }

        //  Public methods and properties
        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public static ViewGroupHistoryState StateData
            {
            get
                {
                if (null == s_state)
                    s_state = new ViewGroupHistoryState ();

                return s_state;
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double AllDropDownWidth
            {
            get
                {
                return GetPropertyAsDouble (s_propname_AllDropDownWidth, 200);
                }
            set
                {
                SetPropertyDouble (s_propname_AllDropDownWidth, value);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double AllDropDownHeight
            {
            get
                {
                return GetPropertyAsDouble (s_propname_AllDropDownHeight, 180);
                }
            set
                {
                SetPropertyDouble (s_propname_AllDropDownHeight, value);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double PreviousDropDownWidth
            {
            get
                {
                return GetPropertyAsDouble (s_propname_PreviousDropDownWidth, 200);
                }
            set
                {
                SetPropertyDouble (s_propname_PreviousDropDownWidth, value);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double PreviousDropDownHeight
            {
            get
                {
                return GetPropertyAsDouble (s_propname_PreviousDropDownHeight, 180);
                }
            set
                {
                SetPropertyDouble (s_propname_PreviousDropDownHeight, value);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double NextDropDownWidth
            {
            get
                {
                return GetPropertyAsDouble (s_propname_NextDropDownWidth, 200);
                }
            set
                {
                SetPropertyDouble (s_propname_NextDropDownWidth, value);
                }
            }

        /*------------------------------------------------------------------------------------**/
        /*--------------+---------------+---------------+---------------+---------------+------*/
        public double NextDropDownHeight
            {
            get
                {
                return GetPropertyAsDouble (s_propname_NextDropDownHeight, 180);
                }
            set
                {
                SetPropertyDouble (s_propname_NextDropDownHeight, value);
                }
            }

        } // ViewGroupHistoryState
    } //namespace Bentley.ViewGroupHistory
@endcode

<H3>Example MstnRibbonState.xml file </H3>

<P>Below is an example state xml file that contains data from two RibbonCoponent Providers. </P>

@code{.unparsed}

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <!--Bentley MstnRibbonState Configuration File.-->
    <!--Modifying this file may render it invalid.-->
    <RibbonState>
      <RibbonViewState xmlns="RibbonState.01.00">
        <ActiveWorkFlowName>Drawing</ActiveWorkFlowName>
        <RibbonMinimizedState>False</RibbonMinimizedState>
        <LineStylePickerShowSearch>True</LineStylePickerShowSearch>
        <LineStylePickerShowRecentStyles>True</LineStylePickerShowRecentStyles>
        <LineStylePickerDisplayMode>All</LineStylePickerDisplayMode>
        <LineStylePickerDropDownWidth>180</LineStylePickerDropDownWidth>
        <LineStylePickerDropDownHeight>500</LineStylePickerDropDownHeight>
     </RibbonViewState>
     <ViewGroupHistoryState xmlns="RibbonState.01.00">
        <PrevDropDownWidth>200</PrevDropDownWidth>
        <PrevDropDownHeight>180</PrevDropDownHeight>
     </ViewGroupHistoryState>
   </RibbonState>
   
@endcode







        
        
        
        
        

 

*****************************************************************************************/


/************************************************************************************//**
* @addtogroup UpdateFiveDeprecatedFunctions
*
* <P>Below are listed a set of functions and methods deprecated in update 5, 10.05.00.xx builds </P>
* 
<H3>Removed :</H3>

@code{.unparsed}

 StatusInt Relationship::Moniker::FromAssocPoint (DgnModelRefP homeModel, DgnPlatform::AssocPoint const& ap);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

 Moniker m (homeModel, ap);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elementIn, DgnModelRefP refModel);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

 Moniker m (homeModel, PersistentElementPath (homeModel, elementIn));

@endcode

<H3>Removed :</H3>


@code{.unparsed}

StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elementIn, DgnPlatform::ElementId refAttid);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

 Moniker m (homeModel, PersistentElementPath (refAttid, elementIn));

@endcode

<H3>Removed :</H3>


@code{.unparsed}

StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, ElementRefP ref, DgnModelRefP refModel);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

 Moniker m (homeModel, PersistentElementPath (refModel, ref));

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt Relationship::Moniker::FromLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elid);

@endcode

 <H3> Replacement : </H3>


@code{.unparsed}

 Moniker m (homeModel, PersistentElementPath (homeModel, elid));

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt Relationship::Moniker::FromLocalElement (DgnModelRefP homeModel, ElementRefP ref);

@endcode

  Use Instead :

@code{.unparsed}

 Moniker m (homeModel, PersistentElementPath (homeModel, ref));

@endcode

<H3>Removed :</H3>

@code{.unparsed}

ElementRefP Relationship::Moniker::EvaluateElementRef ();

@endcode

  Use Instead :


@code{.unparsed}

 Moniker::EvaluateElement().GetElementRef();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

ElementRefP Relationship::ParameterQuery::EvaluateElementRef();

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

 ParameterQuery::GetMoniker ().EvaluateElement().GetElementRef();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt DependencyManagerLinkage::AppendLinkageToMSElement (MSElementP el, DependencyLinkage const& dependencyData, size_t xtrabytes);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

EditElementHandle eeh (el);
DependencyManagerLinkage::AppendLinkage (eeh, dependencyData, xtrabytes);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int DependencyManagerLinkage::DeleteLinkageFromMSElement (MSElementP element, UShort appID, UShort appValue);

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

EditElementHandle eeh (el);
DependencyManagerLinkage::DeleteLinkage (eeh, appID, appValue);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt DependencyManagerLinkage::GetLinkageFromMSElement (DependencyLinkageCP* ppDependencyLinkageInplace, MSElementCP element, UShort appID, UShort appValue);

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

ElementHandle eeh (el);
DependencyManagerLinkage::DeleteLinkage (ppDependencyLinkageInplace, eh, appID, appValue);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

bool LxoSettings::IsSphericalCamera () const; 

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

CAMERAPROJECTION_Spherical == LxoSettings::GetCameraProjection ()

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void LxoSettings::SetIsSphericalCamera (bool value);

@endcode

<H3>Replacement : </H3>


@code{.unparsed}

LxoSettings::SetCameraProjection (CAMERAPROJECTION_Spherical);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

bool mdlAssoc_isTagged (DgnPlatform::ElementId * tagValue, MSElementCP elm);

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

ElementId tagId = mdlElement_getID (&elm);

@endcode


<H3>Removed :</H3>

@code{.unparsed}

int mdlDependency_getDependents (DgnPlatform::ElementId *pDependents, DgnPlatform::ElementId rootElemId, DgnModelRefP rootModelRef, int maxDependents);

@endcode

<H3>Replacement : </H3>

@code{.unparsed}

int  mdlDependency_getDependentElementRefs (ElementRefP *pDependents, DgnPlatform::ElementId rootElemId, DgnModelRefP rootModelRef, int maxDependents);
pDependents[0].GetElementId () // if an element id of a dependent element is required 

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void DEllipse3d::Evaluate (DPoint3dR point, double theta) const;

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

void DEllipse3d::RadiansToPoint (DPoint3dR point, double theta) const;

@endcode

<H3>Removed :</H3>

@code{.unparsed}

DPoint3d DPoint3d::FromXYZ (double x, double y, double z);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

DPoint3d DPoint3d::From (double x, double y, double z);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

bool DoubleOps::SafeDivideDistance (double &result, double numerator, double denominator, double defaultResult = 0.0);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

ValidatedDouble DoubleOps::ValidatedDivideDistance(double a, double b, double defaultResult = 0.0);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

PolyfaceHeaderR IPolyfaceConstruction::GetClientMeshR ();

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

PolyfaceHeaderPtr IPolyfaceConstruction::GetClientMeshPtr ();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

IPolyfaceConstructionPtr IPolyfaceConstruction::New (IFacetOptionsR options);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

IPolyfaceConstructionPtr IPolyfaceConstruction::Create (IFacetOptionsR options);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int MSBsplineCurve::NumberAllocatedKnots () const;

@endcode

<H3>Replacements :</H3>

@code{.unparsed}

size_t MSBsplineCurve::GetNumKnots () const;
int    MSBsplineCurve::GetIntNumKnots () const;

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int MSBsplineCurve::NumberAllocatedPoles () const;

@endcode

<H3>Replacements :</H3>

@code{.unparsed}

size_t MSBsplineCurve::GetNumPoles () const;
int    MSBsplineCurve::GetIntNumPoles () const;

@endcode

<H3>Removed :</H3>

@code{.unparsed}

PolyfaceHeaderPtr PolyfaceHeader::New ();

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

PolyfaceHeaderPtr PolyfaceHeader::CreateVariableSizeIndexed ();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

PolyfaceCoordinateMapPtr PolyfaceCoordinateMap::New (PolyfaceHeaderR polyface);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

PolyfaceCoordinateMapPtr PolyfaceCoordinateMap::Create (PolyfaceHeaderR polyface);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void mdlRMatrix_rotatePoint (DPoint3dP pointP, RotMatrixCP matrixP);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

matrixP->Mutliply (*pointP);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void mdlRMatrix_unrotatePoint (DPoint3dP pointP, RotMatrixCP matrixP);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

void mdlRMatrix_multiplyTransposePoint (DPoint3dP pointP, RotMatrixCP matrixP);

//or (better)

matrixP->MutliplyTranspose (pointP);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void mdlRMatrix_unrotatePointArray (DPoint3dP pointArrayP, RotMatrixCP matrixP, int numPoints);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

matrixP->MultiplyTranspose (pointArrayP, pointArrayP, numPoints);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void mdlTMatrix_rotateScalePoint (DPoint3dP pointP, TransformCP transformP);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

transformP->MultiplyMatrixOnly (*pointP);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlResource_loadFromStringList (WChar *pwString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

StatusInt mdlResource_loadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc* m = NULL);
StatusInt mdlResource_loadWString (WStringP, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum, MdlDesc* m = NULL);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt LoadFromStringList (WChar* pwString, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

StatusInt mdlResource_loadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc* m = NULL);
StatusInt mdlResource_loadWString (WStringP, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum, MdlDesc* m = NULL);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlFilterIterator_setBaseFilter (FilterIteratorP pFilterIteratorIn, FilterID iBaseFilterIdIn);

@endcode

<H3>Replacement :</H3>
Note: the parameter iBaseFilterIdIn from above was always ignored.

@code{.unparsed}

StatusInt mdlFilterIterator_reset (FilterIteratorP pFilterIteratorIn);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int mdlView_setLevels (bool onOffFlagIn, short* v7LevelMask, bool* viewList, bool doUpdate);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

    int         status = ERROR;
    BitMaskP    pWorkingMask;

    mdlBitMask_create(&pWorkingMask, true);
    mdlBitMask_setFromBitArray (pWorkingMask, 64, reinterpret_cast<UShort *>(v7LevelMask));

    status = mdlView_changeLevelDisplayMaskMulti (MASTERFILE, viewList, pWorkingMask, onOffFlagIn ? LevelMaskOperation::On : LevelMaskOperation::Off, doUpdateIn);

    mdlBitMask_free(&pWorkingMask);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

void mdlTag_registerSet (DgnModelRefP modelRef, MSElementCP el, DgnPlatform::ElementId uniqueId);

@endcode

<H3>Replacement :</H3>

There is no replacement the tag is registered automatically when it is added to the file.

<H3>Removed :</H3>

@code{.unparsed}

int         mdlFile_createDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

BeFileName  fileName;

mdlFile_create (&fileName, inname, envvar, iext);
filename.c_str ();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int         mdlFile_findDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

BeFileName  fileName;

mdlFile_find (&fileName, inname, envvar, iext, FINDFILEOPTION_Default);
filename.c_str ();

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int         mdlFile_findExtDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext, FINDFILE_Options options);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

BeFileName  fileName;

mdlFile_find (&fileName, inname, envvar, iext, options);
filename.c_str ();

@endcode


<H3>Removed :</H3>

@code{.unparsed}

IPointCloudClassificationViewSettingsPtr IPointCloudClassificationViewSettings::GetPointCloudClassificationViewSettings(int viewIndex);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

IPointCloudClassificationViewSettingsPtr ptr = IPointCloudClassificationViewSettings::GetPointCloudClassificationViewSettings(viewIndex, ACTIVEMODEL);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

bool IPointCloudClassificationViewSettings::GetClassificationState (UChar idx) const;

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

bool IPointCloudClassificationViewSettings::GetState (UChar idx) const;

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlRaster_systemRasterContainerGet (DgnRasterVectorR  collection);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

ModelRefIterator modelItr(pRootModel, iteratorType, depth);      
for (DgnModelRefP modelRefP = modelItr.GetFirst (); modelRefP; modelRefP = modelItr.GetNext ())
    {
    for each(DgnRasterP rasterP in DgnRasterCollection::GetRasters(modelRefP))
        {
        if(NULL != rasterP)
            //Do something;
        }
    }

@endcode

<H3>Removed :</H3>

@code{.unparsed}

int mdlVec_linePlaneIntersect (DPoint3dP intersectPt, DPoint3dCP linePt, DPoint3dCP lineNormal, DPoint3dCP planePt, DPoint3dCP planeNormal, int perpendicular);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

if (ERROR == mdlVec_linePlaneIntersect (intersectPt, linePt, lineNormal, planePt, planeNormal))
    // line is parallel to the plane.


@endcode

<H3>Removed :</H3>

@code{.unparsed}

DgnWorkSpacePtr DgnWorkSpace::Read (DgnDocumentMonikerCR cfgMoniker);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

DgnWorkSpacePtr DgnWorkSpace::Read(DgnDocumentMonikerCR cfgMoniker, DgnFolderMonikerCR configurationFolderRootPath);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

DgnWorkSetPtr DgnWorkSet::Create(DgnWorkSpaceR workspace, WCharCP name, WCharCP descr);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

DgnWorkSetPtr DgnWorkSet::Create (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker, DgnDocumentMonikerCR dgnwsMoniker, WStringCR name, WCharCP descr);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

DgnWorkSetPtr DgnWorkSet::Read (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker);

@endcode

<H3>Replacement :</H3>

@code{.unparsed}

DgnWorkSetPtr DgnWorkSet::Read (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker, DgnDocumentMonikerCR DgnwsMoniker);

@endcode

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlLevel_getParentId (DgnPlatform::LevelId* pParentLevelIdOut, DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlLevel_getChildCount (int* pChildLevelCountOut, DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

bool mdlLevel_isParent (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

bool mdlLevel_isChild (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

StatusInt mdlLevel_setParentId (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn, DgnPlatform::LevelId parentLevelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

WCharCP mdlLevel_getPathName (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);

@endcode

<H3>Replacement :</H3>

None. Hierarchical levels are not supported anymore.

<H3>Removed :</H3>

@code{.unparsed}

void SheetDef::GetWindowsPrinterName (WString& windowsPrinterName) const;
void SheetDef::SetWindowsPrinterName (WChar const * windowsPrinterName);
void SheetDef::GetPltFileName (WString& pltFileName) const;
void SheetDef::SetPltFileName (WChar const * pltFileName);

@endcode

<H3>Replacement :</H3>

The windows printer name and the plot file names are no longer stored on SheetDef. Their use has been deprecated.

*****************************************************************************************/