APIIntroductionMDL.h
Go to the documentation of this file.
1 /*--------------------------------------------------------------------------------------+
2 |
3 | Supplied under applicable software license agreement.
4 |
5 | Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
6 |
7 +---------------------------------------------------------------------------------------*/
8 #pragma once
9 
10 /************************************************************************************/
125 /************************************************************************************/
133 /************************************************************************************/
161 /************************************************************************************/
249 /************************************************************************************/
357 /************************************************************************************/
464 /************************************************************************************//* Convenience macros for common layouts in
535  #define FLOW_MARGIN 1
536  #define FLOW_HSPACING 1
537  #define FLOW_VSPACING 1
538 
539  // Used for Icon Buttons in a FlowLayout resembling a Toolbar at the top or bottom of a dialog
540  FlowLayoutRsc FLOWLAYOUTID_IconButtons =
541  {
542  {FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN, FLOW_MARGIN}, // Margins - Left, Top, Right, Bottom
543  FLOW_HSPACING, FLOW_VSPACING // HSpacing, VSpacing
544  }; @code{.unparsed}
545 *
546 * @endcode
547 *
548 *<H3>Layout Items</H3>
549 *<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>
550 *
551 *<P>Layout helper macros are provided for each Layout Item and should be used in .r files instead of full item list specifications.</P>
552 *
553 *<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>
554 *<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>
555 *
556 * <table>
557 * <tr>
558 * <th>Layout</th>
559 * <th>Macro</th>
560 * <th>Description</th>
561 * </tr>
562 * <tr>
563 * <td>GridLayout</td>
564 * <td>BEGIN_GRID_LAYOUT(id,auxinfo) </td>
565 * <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>
566 * </tr>
567 * <tr>
568 * <td>FlowLayout</td>
569 * <td>BEGIN_FLOW_LAYOUT(id,auxinfo) </td>
570 * <td>Begins a FlowLayout. Horizontal and vertical spacing may be specified. </td>
571 * </tr>
572 * <tr>
573 * <td>HStackLayout</td>
574 * <td>BEGIN_HSTACK_LAYOUT(id,auxinfo) </td>
575 * <td>Begins a horizontal StackLayout. Horizontal spacing may be specified. </td>
576 * </tr>
577 * <tr>
578 * <td>vstacklayout</td>
579 * <td>BEGIN_HSTACK_LAYOUT(id,auxinfo) </td>
580 * <td>Begins a horizontal StackLayout. Horizontal spacing may be specified. </td>
581 * </tr>
582 * <tr>
583 * <td>HSplitterLayout</td>
584 * <td>BEGIN_HSPLITTER_LAYOUT(id,auxinfo) </td>
585 * <td>Begins a horizontal SplitterLayout. A Sash item should be placed between two items or layouts. </td>
586 * </tr>
587 * <tr>
588 * <td>VSplitterLayout</td>
589 * <td>BEGIN_VSPLITTER_LAYOUT(id,auxinfo) </td>
590 * <td>Begins a vertical SplitterLayout. A Sash item should be placed between two items or layouts. </td>
591 * </tr>
592 * <tr>
593 * <td>DockLayout</td>
594 * <td>BEGIN_DOCK_LAYOUT(id,auxinfo) </td>
595 * <td>Begins a DockLayout. Items and layouts within this layout should specify a DockPosition using EXTINTATTR_DOCK_POSITION or the dockPosition= auxInfo override. </td>
596 * </tr>
597 * <tr>
598 * <td>ENDLayout</td>
599 * <td>END_LAYOUT </td>
600 * <td>Ends the preceding "Begin" layout item. </td>
601 * </tr>
602 * <tr>
603 * <td>GridRow</td>
604 * <td>GRID_ROW(stretch,auxinfo) </td>
605 * <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>
606 * </tr>
607 * <tr>
608 * <td>EndRow</td>
609 * <td>END_ROW </td>
610 * <td>Ends the preceding GridRow. </td>
611 * </tr>
612 * <tr>
613 * <td>Spacing</td>
614 * <td>SPACING(amount) </td>
615 * <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>
616 * </tr>
617 * <tr>
618 * <td>Stretch</td>
619 * <td>STRETCH(amount) </td>
620 * <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>
621 * </tr>
622 * <tr>
623 * <td></td>
624 * <td>AUTO_XY </td>
625 * <td>Defined as 0, 0. Convenience macro for the DialogItemRsc sextant x,y fields to indicate the Layout Manager will determine position </td>
626 * </tr>
627 * <tr>
628 * <td></td>
629 * <td>AUTO_XYWH </td>
630 * <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>
631 * </tr>
632 * <tr>
633 * <td></td>
634 * <td>NO_ITEMARGS </td>
635 * <td>Defined as ON, 0, " ", " ". Convenience macro for the DialogItemRsc attributes, itemArg, label and auxInfo fields</td>
636 * </tr>
637 *</table>
638 *
639 *<H3>Dialog Item Layout Properties</H3>
640 *<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>
641 *<P>GuiLayoutProperties contains the following layout properties. There is a getter and setter for each. </P>
642 *<UL>
643 * <LI><B>Margins</B> - the distance between the outermost pixels of an item or layout and the invisible bounding box of the item.</LI>
644 * <LI><B>Spacing</B> - the distance between items or layouts inside a layout.</LI>
645 * <LI><B>HSpacing</B> - the distance horizontally between items or layouts inside a layout.</LI>
646 * <LI><B>VSpacing</B> - the distance vertically between items or layouts inside a layout </LI>
647 * <LI><B>Stretch</B> - Stretch Factor is used to change how much space items are given in proportion to one another.</LI>
648 * <LI><B>DockPosition</B> - the edge on which a DockLayout places an item.</LI>
649 * <LI><B>Column</B> - the column within a GridLayout in which the item is placed.</LI>
650 * <LI><B>ColSpan</B> - specifies the number of columns a cell should span</LI>
651 * <LI><B>Row</B> - the row within a GridLayout in which the item is placed.</LI>
652 * <LI><B>RowSpan</B> - specifies the number of rows a cell should span.</LI>
653 * <LI><B>SizePolicy</B> - specifies the horizontal and vertical layout behavior of the item.</LI>
654 * <LI><B>Alignment</B> - determines how an item is aligned within the parent layout's allocated space.</LI>
655 * <LI><B>MinSize</B> - specifies the smallest dimensions allowed for an item.</LI>
656 * <LI><B>MaxSize</B> - specifies the largest dimensions allowed for an item.</LI>
657 * <LI><B>OriginalSize</B> - specifies the original dimensions of an item when it was added to a layout.</LI>
658 *</UL>
659 *
660 *<P>The final value of a property for an item is determined by this order of processing: </P>
661 *<OL>
662 * <LI>A default is set in the GuiLayoutProperties constructor</LI>
663 * <LI>Each dialog item type may have its own default, especially in the case of the SizePolicy.</LI>
664 * <LI>An item hook or hook handler may set a value in OnInit () or when processing the DITEM_MESSAGE_INIT message.</LI>
665 * <LI>When reading the item definition, the extendedIntAttribute values are applied (See "Extended Int Attributes and Overrides" below).</LI>
666 * <LI>The 'auxInfo' field override values are applied (See "Extended Int Attributes and Overrides" below).</LI>
667 *</OL>
668 *
669 * @anchor ExtendedIntAttributesandOverrides
670 *
671 *<H3>Extended Int Attributes and Overrides</H3>
672 *<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>
673 *
674 * <table>
675 * <tr>
676 * <th>extendedIntAttribute</th>
677 * <th>Description</th>
678 * <th>auxInfo Override</th>
679 * </tr>
680 * <tr>
681 * <td>EXTINTATTR_MARGIN</td>
682 * <td>Margin for left, top, right &amp; bottom when in a layout. The default is 0. The units specified are in dialog coordinates.</td>
683 * <td>margin='l,t,r,b' (see @ref marginOverride)</td>
684 * </tr>
685 * <tr>
686 * <td>EXTINTATTR_MARGIN_LEFT</td>
687 * <td>Left margin when in a layout</td>
688 * <td>margin= or marginLeft=</td>
689 * </tr>
690 * <tr>
691 * <td>EXTINTATTR_MARGIN_TOP</td>
692 * <td>Top margin when in a layout</td>
693 * <td>margin= or marginTop=</td>
694 * </tr>
695 * <tr>
696 * <td>EXTINTATTR_MARGIN_RIGHT</td>
697 * <td>Right margin when in a layout</td>
698 * <td>margin= or marginRight=</td>
699 * </tr>
700 * <tr>
701 * <td>EXTINTATTR_MARGIN_BOTTOM</td>
702 * <td>Bottom margin when in a layout</td>
703 * <td>margin= or marginBottom=</td>
704 * </tr>
705 * <tr>
706 * <td>EXTINTATTR_SPACING</td>
707 * <td>Spacing for a Layout. The units specified are in dialog coordinates.</td>
708 * <td>spacing=</td>
709 * </tr>
710 * <tr>
711 * <td>EXTINTATTR_STRETCH</td>
712 * <td>Stretch for an item or layout</td>
713 * <td>stretch= (See @ref StretchFactor)</td>
714 * </tr>
715 * <tr>
716 * <td>EXTINTATTR_DOCK_POSITION</td>
717 * <td>Dock Position in a DockLayout; valid values come from the DockPosition enum.</td>
718 * <td>dockPosition= ; valid values are: 'left', 'top', 'right', 'bottom', 'fill'</td>
719 * </tr>
720 * <tr>
721 * <td>EXTINTATTR_COLUMN</td>
722 * <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>
723 * <td>column=</td>
724 * </tr>
725 * <tr>
726 * <td>EXTINTATTR_COLSPAN</td>
727 * <td>Column Span in a GridLayout. The default is 1. A value of -1 is the same as the 'Star' value.</td>
728 * <td>colSpan= (see @ref colSpanOverride)</td>
729 * </tr>
730 * <tr>
731 * <td>EXTINTATTR_ROW</td>
732 * <td>Row in a GridLayout. The default is 0.</td>
733 * <td>row=</td>
734 * </tr>
735 * <tr>
736 * <td>EXTINTATTR_ROWSPAN</td>
737 * <td>Row Span in a GridLayout. The default is 1.</td>
738 * <td>rowSpan=</td>
739 * </tr>
740 * <tr>
741 * <td>EXTINTATTR_HORIZONTAL_ALIGNMENT</td>
742 * <td>Horizontal Alignment in a GridLayout or StackLayout; valid values come from the HorizontalAlignment enum. The default is 'stretch'.</td>
743 * <td>horizontalAlignment= ; valid values are: 'left', 'right', 'center', 'stretch' (see @ref HorizontalAlignment)</td>
744 * </tr>
745 * <tr>
746 * <td>EXTINTATTR_VERTICAL_ALIGNMENT</td>
747 * <td>Vertical Alignment in a GridLayout or StackLayout; valid values come from the VerticalAlignment enum. The default is 'stretch'.</td>
748 * <td>verticalAlignment= ; valid values are: 'top', 'bottom', 'center', 'stretch' (see @ref VerticalAlignment)</td>
749 * </tr>
750 * <tr>
751 * <td>EXTINTATTR_HORIZONTAL_SIZEPOLICY</td>
752 * <td>Horizontal Size Policy; valid values come from the SizePolicyType enum</td>
753 * <td>sizePolicy= (see @ref sizePolicyOverride)</td>
754 * </tr>
755 * <tr>
756 * <td>EXTINTATTR_VERTICAL_SIZEPOLICY</td>
757 * <td>Vertical Size Policy; valid values come from the SizePolicyType enum</td>
758 * <td>sizePolicy= (see @ref sizePolicyOverride)</td>
759 * </tr>
760 * <tr>
761 * <td>EXTINTATTR_MINWIDTH</td>
762 * <td>Minimum Width when in a layout. The units specified are in dialog coordinates.</td>
763 * <td>minWidth=</td>
764 * </tr>
765 * <tr>
766 * <td>EXTINTATTR_MINHEIGHT</td>
767 * <td>Minimum Height when in a layout. The units specified are in dialog coordinates.</td>
768 * <td>minHeight=</td>
769 * </tr>
770 * <tr>
771 * <td>EXTINTATTR_MAXWIDTH</td>
772 * <td>Maximum Width when in a layout. The units specified are in dialog coordinates.</td>
773 * <td>maxWidth=</td>
774 * </tr>
775 * <tr>
776 * <td>EXTINTATTR_MAXHEIGHT</td>
777 * <td>Maximum Height when in a layout. The units specified are in dialog coordinates.</td>
778 * <td>maxHeight=</td>
779 * </tr>
780 *</table>
781 * @note All auxInfo overrides begin with a lower-case letter.
782 * @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.
783 *
784 * @anchor marginOverride
785 *<H3>margin= Override</H3>
786 *<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>
787 *
788 * @anchor sizePolicyOverride
789 *<H3>sizePolicy= Override</H3>
790 *<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>
791 *
792 * @anchor colSpanOverride
793 *<H3>colSpan= Override</H3>
794 *<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>
795 *
796 * @anchor HorizontalAlignment
797 *<H3>HorizontalAlignment</H3>
798 *<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>
799 *
800 *<table>
801 * <tr>
802 * <th>Member</th>
803 * <th>Description</th>
804 * </tr>
805 * <tr>
806 * <td>Left</td>
807 * <td>Items are aligned to the left of the parent layout's allocated layout space.</td>
808 * </tr>
809 * <tr>
810 * <td>Center</td>
811 * <td>Items are aligned to the center of the parent layout's allocated layout space.</td>
812 * </tr>
813 * <tr>
814 * <td>Right</td>
815 * <td>Items are aligned to the right of the parent layout's allocated layout space.</td>
816 * </tr>
817 * <tr>
818 * <td>Stretch (Default)</td>
819 * <td>Items are stretched to fill the parent layout's allocated layout space.</td>
820 * </tr>
821 *</table>
822 *
823 * @anchor VerticalAlignment
824 *<H3>VerticalAlignment</H3>
825 *<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>
826 *
827 *<table>
828 * <tr>
829 * <th>Member</th>
830 * <th>Description</th>
831 * </tr>
832 * <tr>
833 * <td>Left</td>
834 * <td>Items are aligned to the top of the parent layout's allocated layout space.</td>
835 * </tr>
836 * <tr>
837 * <td>Center</td>
838 * <td>Items are aligned to the center of the parent layout's allocated layout space.</td>
839 * </tr>
840 * <tr>
841 * <td>Right</td>
842 * <td>Items are aligned to the bottom of the parent layout's allocated layout space.</td>
843 * </tr>
844 * <tr>
845 * <td>Stretch (Default)</td>
846 * <td>Items are stretched to fill the parent element's allocated layout space.</td>
847 * </tr>
848 *</table>
849 *
850 *<H3>Label Items</H3>
851 *<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>
852 *
853 *<H4>LABEL_LINKPREV and LABEL_LINKNEXT</H4>
854 *<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>
855 *
856 *<H4>LABEL_WORDWRAP</H4>
857 *<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>
858 *
859 *@addtogroup MigrationInstructions
860 *<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>
861 *
862 *@addtogroup Examples
863 *<H2>Dialog Resource Example</H2>
864 *<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>
865 *
866 * @code{.unparsed}
867  DialogBoxRsc DIALOGID_VIEWGROUP_ViewGroups =
868  {
869  DIALOGATTR_DEFAULT | DIALOGATTR_SINKABLE | DIALOGATTR_GROWABLE,
870  DIALOG_LIST_W, DIALOG_H,
871  NOHELP, MHELPTOPIC,
872  HOOKDIALOGID_VIEWGROUP_ViewGroups, NOPARENTID,
873  TXT_ViewGroupDialogTitle,
874  {
875  BEGIN_VSTACK_LAYOUT(0, "")
876 
877  BEGIN_FLOW_LAYOUT (FLOWLAYOUTID_IconButtons, "")
878  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Create, NO_ITEMARGS},
879  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Properties, NO_ITEMARGS},
880  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Delete, NO_ITEMARGS},
881  END_LAYOUT
882 
883  {{ AUTO_XY, VIEWGROUP_LIST_WIDTH, 0}, ListBox, LISTID_VIEWGROUP_ViewGroups, NO_ITEMARGS},
884 
885  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
886  STRETCH(1)
887 
888  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Apply, NO_ITEMARGS},
889  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Close, NO_ITEMARGS},
890  END_LAYOUT
891 
892  END_LAYOUT
893  }
894  };
895 * @endcode
896 *
897 *<H2>Tool Settings Example </H2>
898 *<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>
899 *
900 * @code{.unparsed}
901 * #define W10 10*XC
902 
903  CmdItemListRsc CMD_PLACE_LINE_CONSTRAINED =
904  {{
905  BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "")
906 
907  GRID_ROW(0, "") // row 0
908  {{0, 0, 0, 0}, ToggleButton, TOGGLEID_Length, ON, 0, "", ""}, // column 0
909  {{0, 0, W10, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""}, // column 1
910  {{0, 0, W10, 0}, Text, TEXTID_Length, ON, 0, "", ""}, // column 2
911  END_ROW
912 
913  GRID_ROW(0, "") // row 1
914  {{0, 0, 0, 0}, ToggleButton, TOGGLEID_Angle, ON, 0, "", ""},
915  {{0, 0, W10, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""},
916  {{0, 0, W10, 0}, Text, TEXTID_Angle, ON, 0, "", ""},
917  END_ROW
918 
919  END_LAYOUT
920  }};
921 *
922 * @endcode
923 *
924 *<H2> C++ Layout Manager Example </H2>
925 *<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>
926 *
927 * @code {.unparsed}
928 * virtual bool OnInit (DialogInitArgsR init) override
929  {
930  // Create the GuiLayoutHelper that will hold the top-level layout
931  GuiLayoutHelper *layoutHelper = GuiLayoutHelper::Create (GetDbP());
932 
933  // Create a vertical Stack layout, which is the top-level layout
934  VStackLayout *vStackLayout = VStackLayout::Create();
935  vStackLayout->SetContentsMargins (0);
936 
937  // Get the MenuBar on the dialog and add it to the vertical Stack layout
938  DialogItem *diP = GetDbP()->GetItemByTypeAndId (RTYPE_MenuBar, MENUBARID_CfgVars);
939  if (NULL != diP)
940  vStackLayout->AddControl (GuiLayoutControl::Create(layoutHelper, diP,
941  SizePolicy(ST_Preferred, ST_Fixed)));
942 
943  // Create a horizontal stack layout, which will hold a ListBox on the left
944  // and a ContainerPanel to the right of it.
945  HStackLayout *hStackLayout1 = HStackLayout::Create ();
946 
947  hStackLayout1->AddSpacing (XC);
948 
949  diP = GetDbP()->GetItemByTypeAndId (RTYPE_ListBox, LISTBOXID_ConfigurationTopicList);
950  if (NULL != diP)
951  hStackLayout1->AddControl (GuiLayoutControl::Create(layoutHelper, diP,
952  SizePolicy(ST_Fixed, ST_Preferred)));
953 
954  . . .
955 
956  // Add the horizontal stack layout to the top-level vertical stack layout
957  vStackLayout->AddLayout (hStackLayout1);
958 
959  . . .
960 
961  // Set the vertical stack layout as the top-level layout
962  layoutHelper->SetLayout (vStackLayout);
963 
964  // Set the GuiLayoutHelper as the layout helper for the dialog.
965  // When the dialog size changes or control sizes/properties change,
966  // the layout manager will automatically be invoked.
967  GetDbP()->SetLayoutHelper (layoutHelper);
968 
969  return true;
970  }
971 *
972 *@endcode
973 *
974 *@addtogroup DefaultSizePoliciesforDialogItems
975 *<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>
976 *
977 *<table>
978  <tr><th>Dialog Item Type</th>
979  <th>Default Horizontal Size Policy</th>
980  <th>Default Vertical Size Policy</th></tr>
981 <tr>
982 <td>ButtonGroup</td>
983 <td>Fixed</td>
984 <td>Fixed</td>
985 </tr>
986 <tr>
987 <td>Container</td>
988 <td>Preferred</td>
989 <td>Preferred</td>
990 </tr>
991 <tr>
992 <td>ContainerPanel</td>
993 <td>Preferred</td>
994 <td>Preferred</td>
995 </tr>
996 <tr>
997 <td>ColorChooser</td>
998 <td>Fixed</td>
999 <td>Fixed</td>
1000 </tr>
1001 <tr>
1002 <td>ColorPicker</td>
1003 <td>Minimum</td>
1004 <td>Fixed</td>
1005 </tr>
1006 <tr>
1007 <td>ComboBox</td>
1008 <td>Minimum</td>
1009 <td>Fixed</td>
1010 </tr>
1011 <tr>
1012 <td>CompactSlider</td>
1013 <td>Fixed</td>
1014 <td>Fixed</td>
1015 </tr>
1016 <tr>
1017 <td>FlowDocumentScrollViewer</td>
1018 <td>Preferred</td>
1019 <td>Preferred</td>
1020 </tr>
1021 <tr>
1022 <td>Generic</td>
1023 <td>Fixed</td>
1024 <td>Fixed</td>
1025 </tr>
1026 <tr>
1027 <td>GroupBox</td>
1028 <td>Preferred</td>
1029 <td>Preferred</td>
1030 </tr>
1031 <tr>
1032 <td>IconCmd</td>
1033 <td>Fixed</td>
1034 <td>Fixed</td>
1035 </tr>
1036 <tr>
1037 <td>IconPopup</td>
1038 <td>Minimum</td>
1039 <td>Fixed</td>
1040 </tr>
1041 <tr>
1042 <td>Label</td>
1043 <td>MinimumExpanding</a></td>
1044 <td>Fixed</td>
1045 </tr>
1046 <tr>
1047 <td>Label (with LABEL_WORDWRAP)</td>
1048 <td>Preferred</td>
1049 <td>Preferred</td>
1050 </tr>
1051 <tr>
1052 <td>LevelList</td>
1053 <td>Preferred</td>
1054 <td>Preferred</td>
1055 </tr>
1056 <tr>
1057 <td>ListBox</td>
1058 <td>Preferred</td>
1059 <td>Preferred</td>
1060 </tr>
1061 <tr>
1062 <td>MenuBar</td>
1063 <td>Preferred</td>
1064 <td>Fixed</td>
1065 </tr>
1066 <tr>
1067 <td>MultilineText</td>
1068 <td>MinimumExpanding</td>
1069 <td>MinimumExpanding</td>
1070 </tr>
1071 <tr>
1072 <td>OptionButton</td>
1073 <td>Minimum</td>
1074 <td>Fixed</td>
1075 </tr>
1076 <tr>
1077 <td>PushButton</td>
1078 <td>Minimum</td>
1079 <td>Fixed</td>
1080 </tr>
1081 <tr>
1082 <td>RadioButton</td>
1083 <td>Minimum</td>
1084 <td>Fixed</td>
1085 </tr>
1086 <tr>
1087 <td>Sash (vertical)</td>
1088 <td>Fixed</td>
1089 <td>Expanding</td>
1090 </tr>
1091 <tr>
1092 <td>Sash (horizontal)</td>
1093 <td>Expanding</td>
1094 <td>Fixed</td>
1095 </tr>
1096 <tr>
1097 <td>Scale (vertical)</td>
1098 <td>Fixed</td>
1099 <td>Expanding</td>
1100 </tr>
1101 <tr>
1102 <td>Scale (horizontal)</td>
1103 <td>Expanding</td>
1104 <td>Fixed</td>
1105 </tr>
1106 <tr>
1107 <td>ScrollBar (vertical)</td>
1108 <td>Fixed</td>
1109 <td>Expanding</td>
1110 </tr>
1111 <tr>
1112 <td>ScrollBar (horizontal)</td>
1113 <td>Expanding</td>
1114 <td>Fixed</td>
1115 </tr>
1116 <tr>
1117 <td>Separator (vertical)</td>
1118 <td>Fixed</td>
1119 <td>Expanding</td>
1120 </tr>
1121 <tr>
1122 <td>Separator (horizontal)</td>
1123 <td>Expanding</td>
1124 <td>Fixed</td>
1125 </tr>
1126 <tr>
1127 <td>SpinBox</td>
1128 <td>Minimum</td>
1129 <td>Fixed</td>
1130 </tr>
1131 <tr>
1132 <td>TabPageList</td>
1133 <td>Minimum</td>
1134 <td>Minimum</td>
1135 </tr>
1136 <tr>
1137 <td>Text</td>
1138 <td>Minimum</td>
1139 <td>Fixed</td>
1140 </tr>
1141 <tr>
1142 <td>ToolBox</td>
1143 <td>Fixed</td>
1144 <td>Fixed</td>
1145 </tr>
1146 <tr>
1147 <td>Tree</td>
1148 <td>Preferred</td>
1149 <td>Preferred</td>
1150 </tr>
1151 <tr>
1152 <td>UpDownButtons</td>
1153 <td>Fixed</td>
1154 <td>Fixed</td>
1155 </tr>
1156 <tr>
1157 <td>WinFormsControl</td>
1158 <td>Fixed</td>
1159 <td>Fixed</td>
1160 </tr>
1161 </table>
1162 *
1163 * @addtogroup LayoutManagerErrorMessages
1164 *<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>
1165 *
1166 *<table>
1167  <tr><th>Error Message</th>
1168  <th>Problem Resolution Instructions</th>
1169 <tr>
1170 <td>Parent item for layout instructions is unknown</td>
1171 <td>Layout resource items are only valid in a DialogBoxRsc, DialogItemListRsc or CmdItemListRsc.</td>
1172 </tr>
1173 <tr>
1174 <td>No previous layout item found to add this child layout to</td>
1175 <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>
1176 </tr>
1177 <tr>
1178 <td>Item cannot be outside a layout item</td>
1179 <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>
1180 </tr>
1181 <tr>
1182 <td>The grid row number is invalid. Using 0.</td>
1183 <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>
1184 </tr>
1185 <tr>
1186 <td>The grid column number is invalid. Using 0.</td>
1187 <td>The current column number is less than 0. The default column is 0. Make sure the column='n' syntax is correct.</td>
1188 </tr>
1189 <tr>
1190 <td>Encountered a GridRow outside a GridLayout</td>
1191 <td>The GridRow item may only be located inside a GridLayout / EndLayout block.</td>
1192 </tr>
1193 <tr>
1194 <td>Encountered an EndLayout without a matching "Begin" layout item</td>
1195 <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>
1196 </tr>
1197 <tr>
1198 <td>Spacing item cannot be used in this layout</td>
1199 <td>The Spacing item is only supported in a FlowLayout or StackLayout.</td>
1200 </tr>
1201 <tr>
1202 <td>Stretch item cannot be used in this layout</td>
1203 <td>The Stretch item is only supported in a StackLayout.</td>
1204 </tr>
1205 <tr>
1206 <td>The dialog has no active Layout Manager. Check the layout syntax for the dialog.</td>
1207 <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>
1208 </tr>
1209 <tr>
1210 <td>Invalid DockPosition encountered. Valid values are DOCK_TOP, DOCK_BOTTOM, DOCK_LEFT, DOCK_RIGHT and DOCK_FILL.</td>
1211 <td>EXTINTATTR_DOCK_POSITION and SetDockPosition () only accepts the Top, Bottom, Left, Right and Fill values.</td>
1212 </tr>
1213 <tr>
1214 <td>Invalid margin= value encountered. The value should have one, two or four entries.</td>
1215 <td>See an explanation of the margin= syntax in the @ref marginOverride.</td>
1216 </tr>
1217 <tr>
1218 <td>Invalid integer value override encountered.</td>
1219 <td>Several auxInfo override values should be integer values only. Make sure there are no alpha characters included.</td>
1220 </tr>
1221 <tr>
1222 <td>Invalid dockPosition= value encountered. Valid values are 'top', 'bottom', 'left', 'right' and 'fill'.</td>
1223 <td>The dockPosition= auxInfo override value only accepts the Top, Bottom, Left, Right and Fill values.</td>
1224 </tr>
1225 <tr>
1226 <td>Invalid sizePolicy= value encountered. Valid values are 'minimum', 'maximum', 'preferred', 'minimumexpanding', 'expanding' and 'ignored'.</td>
1227 <td>See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride</td>
1228 </tr>
1229 <tr>
1230 <td>Invalid sizePolicy= value encountered. The value should have two entries for horizontal and vertical.</td>
1231 <td>See an explanation of the sizePolicy= syntax in the @ref sizePolicyOverride</td>
1232 </tr>
1233 <tr>
1234 <td>Invalid horizontalAlignment= value encountered. Valid values are 'left', 'center', 'right' and 'stretch'.</td>
1235 <td>See an explanation of the horizontalAlignment= syntax in the @ref HorizontalAlignment</td>
1236 </tr>
1237 <tr>
1238 <td>Invalid verticalAlignment= value encountered. Valid values are 'top', 'center', 'bottom' and 'stretch'.</td>
1239 <td>See an explanation of the verticalAlignment= syntax in the @ref VerticalAlignment</td>
1240 </tr>
1241 <tr>
1242 <td>The 'Star' syntax for colSpan= cannot be used for this column because the column number is too large.</td>
1243 <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>
1244 </tr>
1245 <tr>
1246 <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>
1247 <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>
1248 </tr>
1249 </table>
1250 *
1251 *
1252 * @addtogroup LayoutManagerMigration
1253 *
1254 *<H2>Introduction </H2>
1255 *<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>
1256 *<P>There are 5 different layout types available in the MDL Layout Manager: </P>
1257 * <OL>
1258 * <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>
1259 * <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
1260 * This type of layout is also called a "Box" layout.</P> </LI>
1261 * <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>
1262 * <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>
1263 * <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>
1264 * </OL>
1265 *
1266 *<H2>Layout Manager Concepts</H2>
1267 *<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>
1268 *
1269 *<H2>Guiding Principles </H2>
1270 *<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>
1271 *
1272 *<H3>Main Dialog Layouts - Grid, VStack or Dock </H3>
1273 *<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>
1274 *
1275 *<H3>Main Tool Settings Layout - VStack</H3>
1276 *<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>
1277 *
1278 *<H3>Use Nested Layouts </H3>
1279 *<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>
1280 *
1281 * @anchor ForToolbarButtonsInADialogUseAFlowLayout
1282 *<H3>For Toolbar buttons in a dialog, use a FlowLayout </H3>
1283 *<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>
1284 *
1285 *<H3>Use Stretch Factor or Stretch Item before overriding Size Policy</H3>
1286 *<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>
1287 *
1288 *<H2>Common Techniques and How To </H2>
1289 *<P>There are a number of common techniques that can be used in many situations when using the Layout Manager. </P>
1290 *
1291 * @anchor AllowForASeparatorAcrossADialog
1292 *<H3>Allow for a Separator across a dialog </H3>
1293 *<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>
1294 *
1295 * @code{.unparsed}
1296 * BEGIN_VSTACK_LAYOUT(0,"")
1297 * . . .
1298 * {AUTO_XYWH, Separator, 0, ON, SEPARATOR_HORIZONTAL, "", ""},
1299 * . . .
1300 * END_LAYOUT
1301 *
1302 * @endcode
1303 *
1304 * @anchor AllowAListBoxItemToBeFlushWithTheDialogEdges
1305 *<H3>Allow a ListBox item to be flush with the dialog edges </H3>
1306 *<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>
1307 *
1308 * @code{.unparsed}
1309 * BEGIN_VSTACK_LAYOUT(0, "")
1310 * . . .
1311 * {{ AUTO_XY, VIEWGROUP_LIST_WIDTH, 0}, ListBox, LISTID_VIEWGROUP_ViewGroups, NO_ITEMARGS},
1312 * . . .
1313 * END_LAYOUT
1314 *
1315 * @endcode
1316 *
1317 *<H3>Allow a MenuBar item to be flush with the dialog edges </H3>
1318 *<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>
1319 *
1320 * @code{.unparsed}
1321 * DItem_MenuBarXRsc MENUBARID_AppMenu =
1322 * {
1323 * NOHOOK, NOARG, MENUBARATTR_TALL,
1324 * {
1325 * {PulldownMenu, PULLDOWNMENUID_AppMenu, "", 0, ""},
1326 * }
1327 * };
1328 *
1329 * BEGIN_VSTACK_LAYOUT(0, "")
1330 * {AUTO_XYWH, MenuBarX, MENUID_AppMenu, NO_ITEMARGS},
1331 * . . .
1332 * END_LAYOUT
1333 *
1334 * @endcode
1335 *
1336 * @anchor PositionOKAndCancelPushButtonsInTheLowerRightCorner
1337 *<H3>Position OK and Cancel Push Buttons in the lower right corner </H3>
1338 *<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>
1339 *
1340 * @code{.unparsed}
1341 * BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
1342  STRETCH(1)
1343  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Apply, NO_ITEMARGS},
1344  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Close, NO_ITEMARGS},
1345  END_LAYOUT
1346 
1347 * @endcode
1348 *
1349 *<H3>Center content when using an HStack </H3>
1350 *<P>To center content in an HStackLayout, insert a STRETCH(1) on either side of those items. </P>
1351 *
1352 * @code{.unparsed}
1353 * BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
1354  STRETCH(1)
1355  {AUTO_XYWH, PushButton, PUSHBUTTONID_CloseElementCommand, ON, 0, "", ""},
1356  STRETCH(1)
1357  END_LAYOUT
1358 
1359 * @endcode
1360 *
1361 * @anchor PreventUnwantedVerticalExpansionWhenUsingAVStack
1362 *<H3>Prevent unwanted vertical expansion when using a VStack </H3>
1363 *<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>
1364 *
1365 * @code{.unparsed}
1366 * BEGIN_VSTACK_LAYOUT(0, "")
1367  . . .
1368  STRETCH(1)
1369  END_LAYOUT
1370 
1371 * @endcode
1372 *
1373 * @anchor PreventUnwantedHorizontalExpansionWhenUsingAHStack
1374 *<H3>Prevent unwanted horizontal expansion when using a HStack </H3>
1375 *<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>
1376 * @code{.unparsed}
1377 * BEGIN_HSTACK_LAYOUT(0, "")
1378  . . .
1379  STRETCH(1)
1380  END_LAYOUT
1381 
1382 * @endcode
1383 *
1384 * @anchor PreventUnwantedHorizontalExpansionInAGridRow
1385 *<H3>Prevent unwanted horizontal expansion in a GridRow </H3>
1386 *<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>
1387 *
1388 * @code{.unparsed}
1389 // Used for "Toggle Label: SettingsItem" formatting. Has a stretch at the end to prevent row stretching.
1390  GridLayoutRsc GRIDLAYOUTID_3ColsToggleLabelSetting =
1391  {
1392  {XC_3_2, XC_3_2, XC_3_2, XC_3_2}, // Margins - Left, Top, Right, Bottom
1393  XC, YC/3, // HSpacing, VSpacing
1394  { // Column Definitions
1395  {0, "toggleColumn3"}, // Stretch, SharedSizeGroup
1396  {0, "labelColumn3"},
1397  {0, "settingColumn3"},
1398  {1, "stretchColumn3"}, // Extra column with a Stretch Factor of 1 to prevent unwanted expansion
1399  }
1400  };
1401 
1402 * @endcode
1403 *
1404 *<H3>Push items to the sides of an HStack </H3>
1405 *<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>
1406 *
1407 * @code{.unparsed}
1408  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
1409  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_MyButton, ON, 0, "", ""},
1410  STRETCH(1)
1411  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_Close, ON, 0, "", ""},
1412  END_LAYOUT
1413 
1414 * @endcode
1415 *
1416 * @anchor AddSpaceBeforeOrAfterAnItem
1417 *<H3>Add space before or after an item </H3>
1418 *<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>
1419 *
1420 * @code{.unparsed}
1421  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUT_LabeledItem, "")
1422  SPACING(SECTION_GAP)
1423  {AUTO_XYWH, Label, 0, ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""},
1424  {AUTO_XYWH, Text, TEXTID_RefDialogRotation, ON, 0, "", ""},
1425  END_LAYOUT
1426 
1427 * @endcode
1428 *
1429 * @anchor MakeOneItemResizable
1430 *<H3>Make one item resizable </H3>
1431 *<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>
1432 *
1433 * @code{.unparsed}
1434  BEGIN_VSTACK_LAYOUT(0,"")
1435  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_Standard, "stretch='1'")
1436  {AUTO_XYWH, ListBox, LISTBOXID_ToolBoxes, ON, 0, "", "stretch='1'"},
1437  . . .
1438  BEGIN_VSTACK_LAYOUT(VSTACKLAYOUTID_Inner,"")
1439  . . .
1440  END_LAYOUT
1441  . . .
1442  END_LAYOUT
1443  . . .
1444  END_LAYOUT
1445 
1446 * @endcode
1447 *
1448 * @anchor PositionAndSizeAnItemsLabel
1449 *<H3>Position and Size an item's label </H3>
1450 *
1451 *<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>
1452 *
1453 *<H4>LABEL_LINKPREV </H4>
1454 * @code{.unparsed}
1455 * BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "")
1456  GRID_ROW(0, "")
1457  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_Length, ON, 0, "", ""},
1458  {{AUTO_XY, W10, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""}, // Pull label from ToggleButton
1459  {{AUTO_XY, W10, 0}, Text, TEXTID_Length, ON, 0, "", ""},
1460  END_ROW
1461  . . .
1462  END_LAYOUT
1463 
1464 * @endcode
1465 *
1466 *<H4>LABEL_LINKNEXT </H4>
1467 * @code{.unparsed}
1468 * BEGIN_GRID_LAYOUT(GRIDLAYOUTID_2ColsLabelSetting, "")
1469  GRID_ROW(0, "")
1470  {{AUTO_XY, W10, 0}, Label, 0, ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""}, // Pull label from OptionButton
1471  {{AUTO_XY, 0, 0}, OptionButton, OPTIONBUTTONID_ElementFill, ON, 0, "", ""},
1472  END_ROW
1473  . . .
1474  END_LAYOUT
1475 
1476 * @endcode
1477 *
1478 *<P>There are convenience macros defined in dlogbox.r.h that simplify working with Labels for layout. These include: </P>
1479 *<UL>
1480 * <LI>LAYOUT_LABEL_PREV_LEFT - link to previous item, align left </LI>
1481 * <LI>LAYOUT_LABEL_PREV_RIGHT - link to previous item, align right </LI>
1482 * <LI>LAYOUT_LABEL_NEXT_LEFT - link to next item, align left </LI>
1483 * <LI>LAYOUT_LABEL_NEXT_RIGHT - link to next item, align right </LI>
1484 *</UL>
1485 *
1486 *<H3>Labeled Item in a FlowLayout </H3>
1487 *<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>
1488 *
1489 * @code{.unparsed}
1490 * BEGIN_FLOW_LAYOUT(FLOWLAYOUTID_IconButtons, "")
1491  . . .
1492  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUT_LabeledItem, "verticalAlignment='center'")
1493  SPACING(XC/2)
1494  {AUTO_XYWH, Label, 0, ON, LABEL_LINKNEXT | ALIGN_RIGHT, "", ""},
1495  {AUTO_XYWH, Text, TEXTID_RefDialogRotation, ON, 0, "", ""},
1496  END_LAYOUT
1497  . . .
1498  END_LAYOUT
1499 *
1500 * @endcode
1501 *
1502 * @anchor SetTheMinimumSizeForAListBox
1503 *<H3>Set the Minimum Size for a ListBox</H3>
1504 *<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>
1505 *
1506 * @code{.unparsed}
1507 * DItem_ListBoxRsc LISTBOXID_ToolBoxes =
1508  {
1509  NOHELP, MHELP, HOOKID_ListBoxStd, NOARG,
1510  LISTATTR_DRAWPREFIXICON|LISTATTR_DYNAMICSCROLL|LISTATTR_FONTBYCOLUMN|LISTATTR_HORIZSCROLLBAR,
1511  10, 0, "",
1512  {
1513  {30*XC, 60, 0, TXT_Show_ToolBoxes},
1514  }
1515  }
1516  extendedIntAttributes
1517  {{
1518  EXTINTATTR_MINWIDTH, 30*XC,
1519  EXTINTATTR_MINHEIGHT, 12*YC
1520  }};
1521 * @endcode
1522 *
1523 *<H3>Span a cell across multiple columns </H3>
1524 *<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>
1525 *
1526 * @code{.unparsed}
1527 * BEGIN_GRID_LAYOUT(GRIDLAYOUTID_3ColsToggleLabelSetting, "")
1528  GRID_ROW(0, "")
1529  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_UseFence, ON, CMD_CHANGE_ATTRIBUTES, "", ""},
1530  {{AUTO_XY, CA_CKBX_CX*XC, 0}, Label, 0, ON, LABEL_LINKPREV, "", ""},
1531  {{AUTO_XY, CA_CTRL_CX*XC, 0}, OptionButton, OPTIONBUTTONID_LockFenceMode, ON, 0, "\0", ""},
1532  END_ROW
1533  GRID_ROW(0, "")
1534  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEBUTTONID_MakeCopy, ON, 0, "", ""},
1535  {{AUTO_XY, CA_CKBX_CX*XC, 0}, Label, 0, ON, LABEL_LINKPREV, "", "colSpan='*'"},
1536  END_ROW
1537  . . .
1538  END_LAYOUT
1539 
1540 * @endcode
1541 *
1542 *
1543 * @addtogroup MigratingDialogs
1544 *
1545 *<P>This section will take two dialogs and migrate them from their older version to using the Layout Manager. </P>
1546 *
1547 *<H2>Manage View Groups Dialog</H2>
1548 *<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>
1549 *
1550 *<H3>Before Image </H3>
1551 * @image html "images/ViewGroups-Before.png"
1552 *
1553 *<H3>After Image </H3>
1554 * @image html "images/ViewGroups-After.png"
1555 *<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>
1556 *<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>
1557 *<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>
1558 *<P>This example uses the following common techniques: </P>
1559 *<UL>
1560 * <LI>@ref ForToolbarButtonsInADialogUseAFlowLayout "For Toolbar buttons in a dialog, use a FlowLayout"</LI>
1561 * <LI>@ref AllowAListBoxItemToBeFlushWithTheDialogEdges "Allow a ListBox Item to be flush with the dialog edges" </LI>
1562 * <LI>@ref MakeOneItemResizable "Make one item resizable"</LI>
1563 * <LI>@ref PositionOKAndCancelPushButtonsInTheLowerRightCorner "Position OK and Cancel Push Buttons in the lower right corner" </LI>
1564 *</UL>
1565 *
1566 *<H3>Before </H3>
1567 *
1568 * @code{.unparsed}
1569 * DialogBoxRsc DIALOGID_VIEWGROUP_ViewGroups =
1570  {
1571  DIALOGATTR_DEFAULT | DIALOGATTR_SINKABLE | DIALOGATTR_GROWABLE,
1572  DIALOG_LIST_W, DIALOG_H,
1573  NOHELP, MHELPTOPIC,
1574  HOOKDIALOGID_VIEWGROUP_ViewGroups, NOPARENTID,
1575  TXT_ViewGroupDialogTitle,
1576  {
1577  @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Create)) // @fadoc 'Create View Group' ...
1578  {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Create, ON, 0, "", ""},
1579  @endif
1580  @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Properties)) // @fadoc 'Edit View Group Properties' ...
1581  {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Properties, ON, 0, "", ""},
1582  @endif
1583  @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Delete)) // @fadoc 'Delete View Group' ...
1584  {{ 0, 0, 0, 0}, IconCmd, ICONCMDID_VIEWGROUP_Delete, ON, 0, "", ""},
1585  @endif
1586  {{ PANEL_ITEM_X, VIEWGROUP_LIST_Y, VIEWGROUP_LIST_WIDTH, 0},
1587  ListBox, LISTID_VIEWGROUP_ViewGroups, ON, 0, "", ""},
1588  {{ RIGHT_CENTER_BUTTON_X, PANEL_ITEM_ROW_AFTER_LIST(1), BUTTON_STDWIDTH*2, 0},
1589  PushButton, PUSHBUTTONID_VIEWGROUP_Apply, ON, 0,"", ""},
1590  {{ LEFT_CENTER_BUTTON_X, PANEL_ITEM_ROW_AFTER_LIST(1), BUTTON_STDWIDTH*2,0},
1591  PushButton, PUSHBUTTONID_VIEWGROUP_Close, ON, 0, "", ""},
1592  }
1593  };
1594 *
1595 * @endcode
1596 *
1597 *<H3>After </H3>
1598 *<P>From usation.rsc </P>
1599 *
1600 * @code (.unparsed)
1601 * // Used for Icon Buttons in a FlowLayout resembling a Toolbar at the top or bottom of a dialog
1602  FlowLayoutRsc FLOWLAYOUTID_IconButtons =
1603  {
1604  {1, 1, 1, 1}, // Margins - Left, Top, Right, Bottom
1605  1, 1 // HSpacing, VSpacing
1606  };
1607 
1608  // Used for OK/Cancel buttons at the bottom of a dialog
1609  HStackLayoutRsc HSTACKLAYOUTID_DialogButtons =
1610  {
1611  {XC_3_2, XC_3_2, XC_3_2, XC_3_2}, // Margins - Left, Top, Right, Bottom
1612  XC_3_2 // Spacing
1613  };
1614 *
1615 * @endcode
1616 *
1617 *<P>From view group code </P>
1618 *
1619 * @code (.unparsed)
1620 * DialogBoxRsc DIALOGID_VIEWGROUP_ViewGroups =
1621  {
1622  DIALOGATTR_DEFAULT | DIALOGATTR_SINKABLE | DIALOGATTR_GROWABLE,
1623  DIALOG_LIST_W, DIALOG_H,
1624  NOHELP, MHELPTOPIC,
1625  HOOKDIALOGID_VIEWGROUP_ViewGroups, NOPARENTID,
1626  TXT_ViewGroupDialogTitle,
1627  {
1628  BEGIN_VSTACK_LAYOUT(0, "")
1629  BEGIN_FLOW_LAYOUT (FLOWLAYOUTID_IconButtons, "")
1630 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Create)) // @fadoc 'Create View Group' ...
1631  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Create, NO_ITEMARGS},
1632 @endif
1633 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Properties)) // @fadoc 'Edit View Group Properties' ...
1634  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Properties, NO_ITEMARGS},
1635 @endif
1636 @if (FeatureAspect (PP_ID_FeatureAspects_View_ViewGroups_Delete)) // @fadoc 'Delete View Group' ...
1637  {AUTO_XYWH, IconCmd, ICONCMDID_VIEWGROUP_Delete, NO_ITEMARGS},
1638 @endif
1639  END_LAYOUT
1640 
1641  {{ AUTO_XY, VIEWGROUP_LIST_WIDTH, 0}, ListBox, LISTID_VIEWGROUP_ViewGroups, NO_ITEMARGS},
1642 
1643  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
1644  STRETCH(1)
1645  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Apply, NO_ITEMARGS},
1646  {{ AUTO_XY, BUTTON_LARGEWIDTH, 0}, PushButton, PUSHBUTTONID_VIEWGROUP_Close, NO_ITEMARGS},
1647  END_LAYOUT
1648  END_LAYOUT
1649  }
1650  };
1651 *
1652 * @endcode
1653 *
1654 *<H2>Tool Boxes Dialog </H2>
1655 *<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>
1656 *
1657 *<H3>Before Image</H3>
1658 * @image html "images/ToolBoxes-Dialog-Before.png"
1659 *
1660 *<H3>After Image</H3>
1661 * @image html "images/ToolBoxes-Dialog-After.png"
1662 *
1663 *<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>
1664 *
1665 *<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>
1666 *
1667 *<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>
1668 *
1669 *<P>Several of the older helper macros dealing with column position and row calculations could be removed after migrating to the Layout Manager. </P>
1670 *
1671 *<P>This example uses the following common techniques: </P>
1672 *<UL>
1673 * <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
1674 * <LI>@ref MakeOneItemResizable "Make one item resizable"</LI>
1675 * <LI>@ref SetTheMinimumSizeForAListBox "Set the Minimum Size for a ListBox"</LI>
1676 * <LI>@ref AddSpaceBeforeOrAfterAnItem "Add space before or after an item"</LI>
1677 * <LI>@ref PositionOKAndCancelPushButtonsInTheLowerRightCorner "Position OK and Cancel Push Buttons in the lower right corner" </LI>
1678 *</UL>
1679 *
1680 *<H3>Before </H3>
1681 *
1682 * @code (.uparsed)
1683 * #define X1 (1*XC) // text & option button x position
1684  #define X2 (2.5*XC)
1685  #define X3 (XSIZE/2)
1686  #define X4 (3.5*XC)
1687  #define Y1 (GENY(1))
1688  #define YGBOX (Y1+YC/2)
1689  #define YLBOX (YGBOX+YC)
1690  #define YLABEL (GENY(12))
1691  #define Y2 (Y1+2*YC)
1692  #define Y3 (Y2+3*YC)
1693  #define Y4 (Y3+2*YC)
1694  #define Y5 (Y4+2*YC)
1695  #define Y6 (Y5+3*YC)
1696 
1697  #define YSEP (GENY(12) + 1.5*YC) // Microsoft Standard says 10 pixels below list box
1698  #define SEP_WIDTH (XSIZE - 2*X1)
1699  #define GBOX_HEIGHT (YLABEL+(1.5*YC)-YGBOX)
1700  #define GBOX_WIDTH (XBUT-35+XC)
1701 
1702  #define YTOGGLE1 (YSEP + 10)
1703  #define YTOGGLE2 (YTOGGLE1 + YC+BGAP)
1704  #define YTOGGLE3 (YTOGGLE2 + YC+BGAP)
1705 
1706  #define XBUT (X2+32*XC+ 35) // Microsoft standard says 35 pixels from the right margin of the list box
1707 
1708  #define BUTTON_WIDTH (BUTTON_STDWIDTH + 10*XC)
1709 
1710  DialogBoxRsc DIALOGID_OpenToolBox =
1711  {
1712  DIALOGATTR_DEFAULT|DIALOGATTR_MODAL|DIALOGATTR_ALWAYSSETSTATE,
1713  XSIZE, YSIZE,
1714  NOHELP, MHELP, HOOKID_Dialog_OpenToolBox, NOPARENTID,
1715  TXT_OpenToolBoxTitle,
1716  {
1717  {{X2,YLBOX,0,0}, ListBox, LISTBOXID_ToolBoxes, ON, 0, "", ""},
1718  {{X2,Y1,0,0}, OptionButton, OPTIONBUTTONID_ListType, ON, 0, "", ""},
1719  {{X2,YLABEL,0,0}, Label, 0, ON, LABEL_FONT_BOLD, TXT_Label_FramesBold, ""},
1720  {{XBUT, Y1,BUTTON_WIDTH,0}, PushButton, PUSHBUTTONID_OK, ON, 0,"", ""},
1721  {{XBUT, Y2,BUTTON_WIDTH,0}, PushButton, PUSHBUTTONID_Cancel, ON, 0, "", ""},
1722  {{XBUT, Y3,BUTTON_WIDTH,0}, PushButton, PUSHBTNID_Reset, ON, 0, "", ""},
1723  {{XBUT, Y4,BUTTON_WIDTH,0}, PushButton, PUSHBTNID_Customize, ON, 0, "", ""},
1724  {{X1, YSEP, SEP_WIDTH,0}, Separator, 0, ON, 0, "", ""},
1725  {{X1, YTOGGLE1, 0,0}, ToggleButton, TOGGLEBTNID_LargeBtns, ON, 0, "", ""},
1726  {{X1, YTOGGLE2, 0,0}, ToggleButton, TOGGLEBTNID_ToolTips, ON, 0, "", ""},
1727  {{X1, YTOGGLE3, 0,0}, ToggleButton, TOGGLEBTNID_ImmediatelyOpen, ON, 0, "", ""},
1728  }
1729  };
1730 *
1731 * @endcode
1732 *
1733 *<H3>After </H3>
1734 *
1735 * @code (.unparsed)
1736 * #define XSIZE (100*XC)
1737  #define YSIZE (30*YC)
1738 
1739  #define BUTTON_WIDTH BUTTON_LARGEWIDTH
1740 
1741  VStackLayoutRsc 1 =
1742  {
1743  {0, 0, 0, 0},
1744  YC/3
1745  };
1746 
1747  DialogBoxRsc DIALOGID_OpenToolBox =
1748  {
1749  DIALOGATTR_DEFAULT|DIALOGATTR_MODAL|DIALOGATTR_ALWAYSSETSTATE|DIALOGATTR_GROWABLE,
1750  XSIZE, YSIZE,
1751  NOHELP, MHELP, HOOKID_Dialog_OpenToolBox, NOPARENTID,
1752  TXT_OpenToolBoxTitle,
1753  {
1754  BEGIN_VSTACK_LAYOUT(0,"")
1755  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "stretch='1'")
1756  {AUTO_XYWH, ListBox, LISTBOXID_ToolBoxes, ON, 0, "", "stretch='1'"},
1757  SPACING(XC)
1758  BEGIN_VSTACK_LAYOUT(1,"")
1759  {AUTO_XYWH, OptionButton, OPTIONBUTTONID_ListType, ON, 0, "", ""},
1760  SPACING(YC)
1761  {AUTO_XYWH, ToggleButton, TOGGLEBTNID_LargeBtns, ON, 0, "", ""},
1762  {AUTO_XYWH, ToggleButton, TOGGLEBTNID_ToolTips, ON, 0, "", ""},
1763  {AUTO_XYWH, ToggleButton, TOGGLEBTNID_ImmediatelyOpen, ON, 0, "", ""},
1764  SPACING(YC)
1765  {{AUTO_XY,BUTTON_WIDTH,0}, PushButton, PUSHBTNID_Reset, ON, 0, "", ""},
1766  {{AUTO_XY,BUTTON_WIDTH,0}, PushButton, PUSHBTNID_Customize, ON, 0, "", ""},
1767  STRETCH(1)
1768  END_LAYOUT
1769  END_LAYOUT
1770 
1771  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_DialogButtons, "")
1772  STRETCH(1)
1773  {{AUTO_XY,BUTTON_WIDTH,0}, PushButton, PUSHBUTTONID_OK, ON, 0,"", ""},
1774  {{AUTO_XY,BUTTON_WIDTH,0}, PushButton, PUSHBUTTONID_Cancel, ON, 0, "", ""},
1775  END_LAYOUT
1776  END_LAYOUT
1777  }};
1778 *
1779 * @endcode
1780 *
1781 *
1782 * @addtogroup MigratingToolSettings
1783 *
1784 *<H2>Place Line </H2>
1785 *<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>
1786 *
1787 * <H3>Before Image</H3>
1788 * @image html "images/PlaceLineTS.png"
1789 
1790 * <H3>After Image</H3>
1791 * @image html "images/CONSGEOM_600_PlaceLine.png"
1792 *
1793 *<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>
1794 *
1795 *<P>This example uses the following principle and common techniques: </P>
1796 *<UL>
1797 * <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
1798 * <LI>@ref PreventUnwantedHorizontalExpansionInAGridRow "To prevent unwanted horizontal expansion in a GridRow" </LI>
1799 * <LI>@ref PositionAndSizeAnItemsLabel "Position and Size an item's label" </LI>
1800 *</UL>
1801 *
1802 *<H3>Before </H3>
1803 *
1804 * @code (.unparsed)
1805 * #define W10 10*XC
1806 
1807  CmdItemListRsc CMD_PLACE_LINE_CONSTRAINED =
1808  {
1809  {
1810  {{X1, Y1, 0, 0}, ToggleButton, TOGGLEID_Length, ON, 0, "", ""},
1811  {{X15, Y1, W10, 0}, Text, TEXTID_Length, ON, 0, "", ""},
1812  {{X1, Y2, 0, 0}, ToggleButton, TOGGLEID_Angle, ON, 0, "", ""},
1813  {{X15, Y2, W10, 0}, Text, TEXTID_Angle, ON, 0, "", ""},
1814  {{X1, Y3, 0, 0}, ToggleButton, TOGGLEID_SolutionChoice, ON|HIDDEN, 0, "", ""},
1815  {{X15, Y3, W10, 0}, OptionButton, OPTIONBUTTONID_SolutionChoice, ON|HIDDEN, 0, "", ""},
1816  {{X1, Y3, W10, 0}, Label, 0, ON, 0, "", ""},
1817  }
1818  };
1819 *
1820 * @endcode
1821 *
1822 *<H3>Before </H3>
1823 *
1824 * <P>From MicroStation </P>
1825 *
1826 * @code (.unparsed)
1827 *
1828 * // Use for all 3 column Grids in Tool Settings
1829 GridLayoutRsc GRIDLAYOUTID_ToolSettings3Cols =
1830 {
1831  {0, 0, 0, 0}, // Margins - Left, Top, Right, Bottom
1832  GRID_HSPACING, GRID_VSPACING, // HSpacing, VSpacing
1833  { // Column Definitions
1834  {0, "ts3_column0"}, // Stretch, SharedSizeGroup
1835  {0, "ts3_column1"},
1836  {0, "ts3_column2"},
1837  {1, "ts3_stretch"}, // Extra column with a Stretch Factor of 1 to prevent unwanted row expansion
1838  }
1839 };
1840 *
1841 * @endcode
1842 *
1843 *<P>From PPModules\2dModeling\Apps\consgeom\transkit\consgeom.r </P>
1844 *
1845 * @code (.unparsed)
1846 *#define W10 10*XC
1847 
1848  CmdItemListRsc ItemList_LineConstrained =
1849  {{
1850  BEGIN_TOOL_SETTINGS
1851  BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
1852  GRID_ROW(0, "")
1853  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_Length, ON, 0, "", ""},
1854  {{AUTO_XY, W10, 0}, Label, 0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
1855  {{AUTO_XY, W10, 0}, Text, TEXTID_Length, ON, 0, "", ""},
1856  END_ROW
1857  GRID_ROW(0, "")
1858  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_Angle, ON, 0, "", ""},
1859  {{AUTO_XY, W10, 0}, Label, 0, ON, LABEL_LINKPREV| ALIGN_RIGHT, "", ""},
1860  {{AUTO_XY, W10, 0}, Text, TEXTID_Angle, ON, 0, "", ""},
1861  END_ROW
1862  GRID_ROW(0, "")
1863  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_SolutionChoice, ON|HIDDEN, 0, "", ""},
1864  {{AUTO_XY, W10, 0}, Label, LABELID_SolutionChoice, ON|HIDDEN, LABEL_LINKPREV| ALIGN_RIGHT, "", ""},
1865  {{AUTO_XY, W10, 0}, OptionButton, OPTIONBUTTONID_SolutionChoice, ON|HIDDEN, 0, "", ""},
1866  END_ROW
1867  END_LAYOUT
1868  END_TOOL_SETTINGS
1869  }};
1870 *
1871 * @endcode
1872 *
1873 *<H2>Change Attributes </H2>
1874 *
1875 *<P>The following example is the "Change Attributes" command. </P>
1876 <H3>Before Image</H3>
1877 * @image html "images/ChangeAttributesTS.png"
1878 
1879 *<H3>After Image</H3>
1880 * @image html "images/CHANGEATTRIBS_3800_ChangeAttributes.png"
1881 *
1882 *<P> These settings basically have 3 sections:</P>
1883 *<OL>
1884 * <LI>The "Use Active Attributes" section </LI>
1885 * <LI>Several "Toggle Label: Editor" rows </LI>
1886 * <LI>more Toggles, one with an editor, and two without </LI>
1887 *</OL>
1888 *
1889 *<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>
1890 *
1891 *<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>
1892 *
1893 *<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>
1894 *
1895 *<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>
1896 *
1897 *<P>Several of the older helper macros dealing with column position and row calculations could be removed after migrating to the Layout Manager. </P>
1898 *
1899 *<P>This example uses the following principle and common techniques: </P>
1900 *
1901 *<UL>
1902 * <LI>@ref AddSpaceBeforeOrAfterAnItem "Add space before or after an item"</LI>
1903 * <LI>@ref PreventUnwantedHorizontalExpansionWhenUsingAHStack "Prevent unwanted horizontal expansion when using a HStack" </LI>
1904 * <LI>@ref AllowForASeparatorAcrossADialog "Allow for a Separator across a dialog" </LI>
1905 * <LI>@ref PreventUnwantedVerticalExpansionWhenUsingAVStack "To prevent unwanted vertical expansion" </LI>
1906 * <LI>@ref PreventUnwantedHorizontalExpansionInAGridRow "To prevent unwanted horizontal expansion in a GridRow" </LI>
1907 * <LI>@ref PositionAndSizeAnItemsLabel "Position and Size an item's label" </LI>
1908 *</UL>
1909 *
1910 *<H3>Before</H3>
1911 *
1912 * @code (.unparsed)
1913 *
1914 * #define CA_CTRL_CX 17
1915  #define CA_CKBX_CX 16
1916  #define CA_UAA_CX (20*XC)
1917  #define CA_MElm_X (22*XC)
1918  #define CA_ROW(x) D_ROW(x)
1919  #define CA_CTRL_X (17*XC)
1920 
1921  CmdItemListRsc CMD_CHANGE_ATTRIBUTES =
1922  {{
1923  {{XC, CA_ROW( 1.0), CA_UAA_CX, 0}, ToggleButton, TOGGLEBUTTONID_UseActiveAttributes, ON, 0, "", ""},
1924  {{CA_MElm_X, CA_ROW( 0.8), 0, 0}, IconCmdX, ICONCMDX_MatchElementAttr, ON, 0, "", ""},
1925  {{0, CA_ROW( 2.2), 0, 0}, Separator, 0, ON, 0, "", ""},
1926  {{XC, CA_ROW( 2.7), CA_CKBX_CX*XC, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmLevel, ON, 0, "", ""},
1927  {{CA_CTRL_X, CA_ROW( 2.7), CA_CTRL_CX*XC, 0}, ComboBox, COMBOBOXID_ElmLevel, DISABLED, 0, "", ""},
1928  {{XC, CA_ROW( 3.7), CA_CKBX_CX*XC, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmOutlineColor, ON, 0, "", ""},
1929  {{CA_CTRL_X, CA_ROW( 3.7), CA_CTRL_CX*XC, 0}, IconPopup, ICONPOPUPID_ElmOutlineColor, DISABLED, 0, "", ""},
1930  . . .
1931  {{0, CA_ROW(10.8), 0, 0}, Separator, 0, ON, 0, "", ""},
1932  {{XC, CA_ROW(11.2), 0, 0}, ToggleButton, TOGGLEID_UseFence, ON, CMD_CHANGE_ATTRIBUTES,"",""},
1933  {{15*XC, CA_ROW(11.2), 0, 0}, OptionButton, OPTIONBUTTONID_LockFenceMode, ON, 0, "\0", ""},
1934  {{XC, CA_ROW(12.2), 0, 0}, ToggleButton, TOGGLEBUTTONID_MakeCopy, ON, 0, "", ""},
1935  . . .
1936  }};
1937 *
1938 * @endcode
1939 *
1940 *<H3>After </H3>
1941 *
1942 *@code (.unparsed)
1943 * #define CA_CTRL_CX 17
1944  #define CA_CKBX_CX 12
1945 
1946 CmdItemListRsc ItemList_ChangeAttributes =
1947  {{
1948  BEGIN_TOOL_SETTINGS
1949  BEGIN_VSTACK_LAYOUT (VSTACKLAYOUTID_Inner, "")
1950  BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
1951  GRID_ROW(0, "")
1952  EMPTY_GRID_CELL(0,"")
1953  EMPTY_GRID_CELL(0,"")
1954  BEGIN_HSTACK_LAYOUT(HSTACKLAYOUTID_ToolSettingsButtons, "column='2',colSpan='*'")
1955  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEBUTTONID_UseActiveAttributes, ON, 0, "", ""},
1956  {{AUTO_XY, 0, 0}, IconCmdX, ICONCMDX_MatchElementAttr, ON, 0, "", ""},
1957  END_LAYOUT
1958  END_ROW
1959  END_LAYOUT
1960 
1961  {AUTO_XYWH, Separator, 0, ON, SEPARATOR_HTOOLSETTINGS, "", ""},
1962 
1963  BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
1964  GRID_ROW(0, "")
1965  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmLevel, ON, 0, "", ""},
1966  {{AUTO_XY, CA_CKBX_CX*XC, 0}, Label, 0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
1967  {{AUTO_XY, CA_CTRL_CX*XC, 0}, ComboBox, COMBOBOXID_ElmLevel, DISABLED, 0, "", ""},
1968  END_ROW
1969  GRID_ROW(0, "")
1970  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEBUTTONID_ChangeElmOutlineColor, ON, 0, "", ""},
1971  {{AUTO_XY, CA_CKBX_CX*XC, 0}, Label, 0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
1972  {{AUTO_XY, CA_CTRL_CX*XC, 0}, IconPopup, ICONPOPUPID_ElmOutlineColor, DISABLED, 0, "", ""},
1973  END_ROW
1974 . . .
1975  END_LAYOUT
1976 
1977  {AUTO_XYWH, Separator, 0, ON, SEPARATOR_HTOOLSETTINGS, "", ""},
1978 
1979  BEGIN_GRID_LAYOUT(GRIDLAYOUTID_ToolSettings3Cols, "")
1980  GRID_ROW(0, "")
1981  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEID_UseFence, ON, CMD_CHANGE_ATTRIBUTES, "", ""},
1982  {{AUTO_XY, CA_CKBX_CX*XC, 0}, Label, 0, ON, LABEL_LINKPREV | ALIGN_RIGHT, "", ""},
1983  {{AUTO_XY, CA_CTRL_CX*XC, 0}, OptionButton, OPTIONBUTTONID_LockFenceMode, ON, 0, "\0", ""},
1984  END_ROW
1985  GRID_ROW(0, "")
1986  {{AUTO_XY, 0, 0}, ToggleButton, TOGGLEBUTTONID_MakeCopy, ON, 0, "", "column='2',colSpan='*'"},
1987  END_ROW
1988 . . .
1989  END_LAYOUT
1990 
1991  STRETCH (1)
1992  END_LAYOUT
1993  END_TOOL_SETTINGS
1994  }};
1995  }};
1996 *
1997 * @endcode
1998 *
1999 *
2000 *
2001 *
2002 *
2003 *
2004 *
2005 *
2006 *
2007 *****************************************************************************************/
2008 
2009 /************************************************************************************/
2274 /************************************************************************************/
2299 /************************************************************************************/
2305 /************************************************************************************/
2353 /************************************************************************************/
2522 /************************************************************************************/
2621 /************************************************************************************/
2724 /************************************************************************************/
2801 /************************************************************************************/
2966 /************************************************************************************/
3054 /************************************************************************************/
3144 /************************************************************************************/
3191 /************************************************************************************/
3394 /************************************************************************************/
3476 /************************************************************************************/
3984 /************************************************************************************/
4037 /************************************************************************************/
4127 /************************************************************************************/
4658 /************************************************************************************/
4784 /************************************************************************************/
4929 /************************************************************************************/
5089 /************************************************************************************/
5198 /************************************************************************************/
5285 /************************************************************************************/
5355 /************************************************************************************/
5507 /************************************************************************************/
5647 /************************************************************************************/
5748 /************************************************************************************/
5901 /************************************************************************************/
6009 /************************************************************************************/
6060 /************************************************************************************/
6164 /************************************************************************************/
6267 /************************************************************************************/
6287 /************************************************************************************/
6399 /************************************************************************************/
6530 /************************************************************************************/
6691 /************************************************************************************/
6792 /************************************************************************************/
6846 /************************************************************************************/
7056 /************************************************************************************/
7287 /************************************************************************************/
7294 /************************************************************************************/
9155 /************************************************************************************/
10102 /************************************************************************************/
10110 /************************************************************************************/
10192 /************************************************************************************/
10247 /************************************************************************************/
10254 /************************************************************************************/
11190 /************************************************************************************/
11326 
11337 
11348 
11362 
11421 
11433 
11537 
11553 
11561 
11569 
11576 
11588 
11613 
11636 
11647 
11691 
11703 
11751 
11763 
11775 
12667 @endcode
12668 
12669 <P> And an example of XCommand definition is shown below. </P>
12670 
12671 @code{.unparsed}
12672 
12673  {"DrawingAids.Locks.Axis",
12674  {CMD_LOCK_AXIS_TOGGLE, MTASKID, ""},
12675  "AxisLock",
12676  TXT6_SettingsSubLockAxis,
12677  "",
12678  "DrawingAids.Locks.Axis", "", "", "[ActiveLock]ActiveLock.AxisLockEnabled()", "", NOACCEL,
12679  PP_ID_FeatureAspects_DrawingAids_Locks_Axis}, // @fadoc DrawingAids.Locks.Axis XCommand
12680 
12681  {"DrawingAids.Locks.ConstructSnap",
12682  {CMD_LOCK_SNAP_ACS_TOGGLE, MTASKID, ""},
12683  "ACSSnapLock",
12684  TXT6_SettingsSubLockConstructSnap,
12685  "",
12686  "DrawingAids.Locks.ConstructSnap", "", "", "[ActiveLock]ActiveLock.ConstructionPlaneLockEnabled()", "", NOACCEL,
12687  PP_ID_FeatureAspects_DrawingAids_Locks_SettingsMenu}, // @fadoc DrawingAids.Locks.ConstructSnap XCommand
12688 
12689 
12690 @endcode
12691 
12692 
12693 <H4>User Defined XCommands</H4>
12694 
12695 <P>User defined XCommands are defined in XML files. Below is an example of XML defined commands. </P>
12696 
12697 @code{.unparsed}
12698 <UserNamedCommands>
12699  <UserNamedCommand>
12700  <Name>GeneralExample.PlaceThickCircle</Name>
12701  <Label>Thick Circle</Label>
12702  <Description>Place thick circle</Description>
12703  <Keyin>[CONSGEOM]PLACE CIRCLE ICON;co=4;wt=4;lc=0</Keyin>
12704  <IconName>PlaceCircle</IconName>
12705  </UserNamedCommand>
12706  <UserNamedCommand>
12707  <Name>GeneralExample.ToolWithNoIcon</Name>
12708  <Label>Place Line</Label>
12709  <Description>Place Line (No Icon)</Description>
12710  <Keyin>PLACE LINE;co=4;wt=4;lc=0</Keyin>
12711  </UserNamedCommand>
12712  <UserNamedCommand>
12713  <Name>GeneralExample.PlaceThinShape</Name>
12714  <Label>Thin Shape</Label>
12715  <Description>Place thin shape</Description>
12716  <Keyin>[CONSGEOM]PLACE SHAPE CONSTRAINED;co=1;wt=0;lc=0</Keyin>
12717  <IconName>PlaceShape</IconName>
12718  </UserNamedCommand>
12719  <UserNamedCommand>
12720  <Name>GeneralExample.PlaceSolidSlab</Name>
12721  <Label>Place Slab</Label>
12722  <Description>Place slab</Description>
12723  <Keyin>[SOLIDMODELING]PLACE SLAB ICON;co=5;wt=2;lc=0</Keyin>
12724  <IconName>PlaceSlab</IconName>
12725  <VisibilityExpression>[Session]Session.TreatActiveModelAs3D()</VisibilityExpression>
12726  </UserNamedCommand>
12727 </UserNamedCommands>
12728 @endcode
12729 
12730 <H3>Example <CommandData> Specifications</H3>
12731 <P>The XML format supports multiple types of Command specification. The recommended Command Type is NamedCommand.</P>
12732 
12733 <H4>NamedCommand </H4>
12734 <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>
12735 
12736 @code{.unparsed}
12737 
12738 <CommandData Type="NamedCommand">
12739  <NamedCommand>Mstn.Cells.CellSelector
12740  <CmdParameters>CELLSEL DIALOG CELLSEL</CmdParameters>
12741  <Icon Type="NamedIcon">
12742  <NamedIcon>Cell</NamedIcon>
12743  </Icon>
12744  </NamedCommand>
12745 </CommandData>
12746 
12747 @endcode
12748 
12749 <H4>UserKeyinCommand </H4>
12750 <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>
12751 
12752 @code{.unparsed}
12753 
12754 <CommandData Type="UserKeyinCommand">
12755  <UserKeyinCommand>
12756  <Label>Database Disconnect</Label>
12757  <Description>Disconnect from the database</Description>
12758  <Keyin>DBCONMGR DISCONNECT</Keyin>
12759  <Icon Type="NamedIcon">
12760  <NamedIcon>Database-Disconnect</NamedIcon>
12761  </Icon>
12762  </UserKeyinCommand>
12763 </CommandData>
12764 @endcode
12765 
12766 <H3>Example <Icon> Specifications </H3>
12767 
12768 <P>Named Ico - Ico is either in ustnicons.rsc or in a DGNLIB. </P>
12769 
12770 @code{.unparsed}
12771 
12772  <Icon Type="NamedIcon">
12773  <NamedIcon>Circle</NamedIcon>
12774  </Icon>
12775 
12776 @endcode
12777 
12778 <P>Mdl-based IconCmd Resource from MicroStation or MDL Application. </P>
12779 
12780 @code{.unparsed}
12781  <Icon Type="RscIcon">
12782  <RscIcon>
12783  <RscType>IconCmd</RscType>
12784  <RscId>-384</RscId>
12785  <TaskId>USTN</TaskId>
12786  </RscIcon>
12787  </Icon>
12788 
12789 @endcode
12790 <H3> <Visibility> Specification </H3>
12791 
12792 <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>
12793 
12794 @code{.unparsed}
12795 
12796  <Visibility>
12797  <ShowExpression>[Session]not(Session.TreatActiveModelAs3D())</ShowExpression>
12798  <FeatureAspect>Surfaces_Modify</FeatureAspect>
12799  </Visibility>
12800 
12801 @endcode
12802 
12803 <H2> UI Synchronization Event System </H2>
12804 <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>
12805 
12806 @code{.unparsed}
12807 DialogManager::SendUISyncMessage (UInt32 syncGroupRscId, MdlDescP mdlDesc, UInt32 syncItemId);
12808 
12809 @endcode
12810 
12811 <P>From a managed application a caller would use the following method.</P>
12812 
12813 @code{.unparsed}
12814 UMDialogManager::SendUISyncMessage (System::String^ synchItemString);
12815 
12816 @endcode
12817 
12818 <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>
12819 <P>DialogManager::SendUISyncMessage (SYNCGROUPID_SystemEvent, NULL, SYNCITEM_SystemEvent_ActiveModelChanged); </P>
12820 <P>This in turn tells every component that has specified interest in the ActiveModelChanged event. </P>
12821 
12822 @code{.unparsed}
12823 
12824  <SplitButtonRef Name="Mstn.Placement.CreateCurves3D" Priority="500000">
12825  <SplitButtonParams Size="Small">
12826  <AccessText>PU</AccessText>
12827  <PopupAccessText>U</PopupAccessText>
12828  <ApplicationParams>
12829  <ApplicationParam>
12830  <Name>MatchingKeyTipItems</Name>
12831  <Value>Mstn.Placement.CreateCurves2D</Value>
12832  </ApplicationParam>
12833  </ApplicationParams>
12834  <SyncItemEvent>SystemEvent.ActiveModelChanged</SyncItemEvent>
12835  <Visibility>
12836  <ShowExpression>[Session]Session.TreatActiveModelAs3D()</ShowExpression>
12837  <FeatureAspect />
12838  </Visibility>
12839  </SplitButtonParams>
12840  </SplitButtonRef>
12841 
12842 @endcode
12843 
12844 <P>The Sync Resources are loaded into MicroStation as it starts in the function guiDialog_startupInit (mstn/mscore/gui/guidlog.cpp). <P>
12845 
12846 <H3>Sync Group Resource Specification </H3>
12847 
12848 <P>The following list of sync events are available for R1 of MicroStation CONNECT:</P>
12849 
12850 @code{.unparsed}
12851 
12852 // Maximum of 32 SyncItems per group
12853 SyncGroupRsc SYNCGROUPID_ActiveLock =
12854 {
12855 "ActiveLock",
12856  {
12857  {SYNCITEM_ActiveLock_Association, "Association"},
12858  {SYNCITEM_ActiveLock_Snap, "Snap"},
12859  {SYNCITEM_ActiveLock_Grid, "Grid"},
12860  {SYNCITEM_ActiveLock_Unit, "Unit"},
12861  {SYNCITEM_ActiveLock_Angle, "Angle"},
12862  {SYNCITEM_ActiveLock_Textnode, "Textnode"},
12863  {SYNCITEM_ActiveLock_Axis, "Axis"},
12864  {SYNCITEM_ActiveLock_Scale, "Scale"},
12865  {SYNCITEM_ActiveLock_GraphGroup, "GraphGroup"},
12866  {SYNCITEM_ActiveLock_Level, "Level"},
12867  {SYNCITEM_ActiveLock_FenceMode, "FenceMode"},
12868  {SYNCITEM_ActiveLock_CellStretch, "CellStretch"},
12869  {SYNCITEM_ActiveLock_Construction, "Construction"},
12870  {SYNCITEM_ActiveLock_Isometric, "Isometric"},
12871  {SYNCITEM_ActiveLock_Depth, "Depth"},
12872  {SYNCITEM_ActiveLock_Isoplane, "Isoplane"},
12873  {SYNCITEM_ActiveLock_UseAnnotationScale, "UseAnnotationScale"},
12874  {SYNCITEM_ActiveLock_ConstructionSnap, "ConstructionSnap"},
12875  {SYNCITEM_ActiveLock_ElementTemplateAssociation, "ElementTemplateAssociation"},
12876  {SYNCITEM_ActiveLock_AccuSnap, "AccuSnap"},
12877  }
12878 };
12879 // Maximum of 32 SyncItems per group
12880 SyncGroupRsc SYNCGROUPID_SystemEvent =
12881 {
12882 "SystemEvent",
12883  {
12884  {SYNCITEM_SystemEvent_ActiveModelChanged, "ActiveModelChanged"},
12885  {SYNCITEM_SystemEvent_AvailableModelsChanged, "AvailableModelsChanged"},
12886  {SYNCITEM_SystemEvent_ModelPropertiesChanged, "ModelPropertiesChanged"},
12887  {SYNCITEM_SystemEvent_FileClose, "FileClose"},
12888  {SYNCITEM_SystemEvent_FileOpen, "FileOpen"},
12889  {SYNCITEM_SystemEvent_ActiveViewChanged, "ActiveViewChanged"},
12890  {SYNCITEM_SystemEvent_AvailableViewsChanged, "AvailableViewsChanged"},
12891  {SYNCITEM_SystemEvent_ClipboardUpdated, "ClipboardUpdated"},
12892  {SYNCITEM_SystemEvent_AvailableLevelsChanged, "AvailableLevelsChanged"},
12893  {SYNCITEM_SystemEvent_PopSetStateChanged, "PopSetStateChanged"},
12894  {SYNCITEM_SystemEvent_ColorMapChanged, "ColorMapChanged"},
12895  {SYNCITEM_SystemEvent_UndoRedoFinished, "UndoRedoFinished"},
12896  {SYNCITEM_SystemEvent_UndoMarkSet, "UndoMarkSet"},
12897  {SYNCITEM_SystemEvent_InitializeUI, "InitializeUI"},
12898  {SYNCITEM_SystemEvent_SelectionSetChanged, "SelectionSetChanged"},
12899  {SYNCITEM_SystemEvent_ContextualTabSetKeyChanged, "ContextualTabSetKeyChanged"},
12900  {SYNCITEM_SystemEvent_TableCellSelectionChanged, "TableCellSelectionChanged"},
12901  {SYNCITEM_SystemEvent_LuxologyRenderStateChanged, "LuxologyRenderStateChanged"},
12902  {SYNCITEM_SystemEvent_ApplicationSyncUIItem, "ApplicationSyncUIItem"},
12903  {SYNCITEM_SystemEvent_AnimationPreviewStateChanged, "AnimationPreviewStateChanged"},
12904  {SYNCITEM_SystemEvent_DgnHistoryStateChange, "DgnHistoryStateChange"},
12905  {SYNCITEM_SystemEvent_AvailableLineStylesChanged, "AvailableLineStylesChanged"},
12906  {SYNCITEM_SystemEvent_ImmediateLineStylesRefreshRequired, "ImmediateLineStylesRefreshRequired"},
12907  {SYNCITEM_SystemEvent_ACSOperationProcessed, "ACSOperationProcessed"},
12908  {SYNCITEM_SystemEvent_RefreshAvailableViewGroupList, "RefreshAvailableViewGroupList"},
12909  {SYNCITEM_SystemEvent_ViewGroupHistoryStateChange, "ViewGroupHistoryStateChange"},
12910  {SYNCITEM_SystemEvent_ContextualTabActivated, "ContextualTabActivated"},
12911  {SYNCITEM_SystemEvent_UserSigninStateChanged, "UserSigninStateChanged"},
12912  }
12913 };
12914 // Maximum of 32 SyncItems per group
12915 SyncGroupRsc SYNCGROUPID_SessionEvent =
12916 {
12917 "SessionEvent",
12918  {
12919  {SYNCITEM_SessionEvent_BeforeProjectChange, "BeforeProjectChange"},
12920  {SYNCITEM_SessionEvent_AfterProjectChange, "AfterProjectChange"},
12921  {SYNCITEM_SessionEvent_RibbonDefinitionCfgVarChanged, "RibbonDefinitionCfgVarChanged"},
12922  {SYNCITEM_SessionEvent_RibbonTabActivated, "RibbonTabActivated"},
12923  {SYNCITEM_SessionEvent_RibbonQATToolListChanged, "RibbonQATToolListChanged"},
12924  {SYNCITEM_SessionEvent_RibbonWorkflowChanged, "RibbonWorkflowChanged"},
12925  }
12926 };
12927 // Maximum of 32 SyncItems per group
12928 SyncGroupRsc SYNCGROUPID_CustomizationChanged =
12929 {
12930 "CustomizationChanged",
12931  {
12932  {SYNCITEM_CustomizationChanged_AvailableTasksChanged, "AvailableTasksChanged"},
12933  {SYNCITEM_CustomizationChanged_AvailableMainTasksChanged, "AvailableMainTasksChanged"},
12934  {SYNCITEM_CustomizationChanged_AvailableNameToolboxesChanged, "AvailableNamedToolboxesChanged"},
12935  {SYNCITEM_CustomizationChanged_AvailableElementTemplatesChanged, "AvailableElementTemplatesChanged"},
12936  {SYNCITEM_CustomizationChanged_KeyboardShortcutsChanged, "KeyboardShortcutsChanged"},
12937  {SYNCITEM_CustomizationChanged_TaskNavigationTaskChanged, "TaskNavigationTaskChanged"},
12938  {SYNCITEM_CustomizationChanged_AvailableColorBookColorsChanged, "AvailableColorBookColorsChanged"},
12939  }
12940 };
12941 // Maximum of 32 SyncItems per group
12942 SyncGroupRsc SYNCGROUPID_SymbologyChanged =
12943 {
12944 "SymbologyChanged",
12945  {
12946  {SYNCITEM_SymbologyChanged_AreaMode, "AreaMode"},
12947  {SYNCITEM_SymbologyChanged_CapMode, "CapMode"},
12948  {SYNCITEM_SymbologyChanged_Color, "Color"},
12949  {SYNCITEM_SymbologyChanged_LineWeight, "LineWeight"},
12950  {SYNCITEM_SymbologyChanged_Level, "Level"},
12951  {SYNCITEM_SymbologyChanged_Class, "Class"},
12952  {SYNCITEM_SymbologyChanged_FillMode, "FillMode"},
12953  {SYNCITEM_SymbologyChanged_FillColor, "FillColor"},
12954  {SYNCITEM_SymbologyChanged_LineStyle, "LineStyle"},
12955  {SYNCITEM_SymbologyChanged_DisplayPriority, "DisplayPriority"},
12956  {SYNCITEM_SymbologyChanged_CellName, "CellName"},
12957  {SYNCITEM_SymbologyChanged_Terminator, "Terminator"},
12958  {SYNCITEM_SymbologyChanged_Point, "Point"},
12959  {SYNCITEM_SymbologyChanged_PatternCell, "PatternCell"},
12960  {SYNCITEM_SymbologyChanged_PatternDelta, "PatternDelta"},
12961  {SYNCITEM_SymbologyChanged_PatternAngle, "PatternAngle"},
12962  {SYNCITEM_SymbologyChanged_Scale, "Scale"},
12963  {SYNCITEM_SymbologyChanged_AreaPatternDelta, "AreaPatternDelta"},
12964  {SYNCITEM_SymbologyChanged_AreaPatternAngle, "AreaPatternAngle"},
12965  {SYNCITEM_SymbologyChanged_PatternScale, "PatternScale"},
12966  {SYNCITEM_SymbologyChanged_TerminatorScale, "TerminatorScale"},
12967  {SYNCITEM_SymbologyChanged_Transparency, "Transparency"},
12968  {SYNCITEM_SymbologyChanged_Angle, "Angle"},
12969  {SYNCITEM_SymbologyChanged_LineStyleParams, "LineStyleParams"},
12970  {SYNCITEM_SymbologyChanged_ElementTemplate, "ElementTemplate"},
12971  }
12972 };
12973 // Maximum of 32 SyncItems per group
12974 SyncGroupRsc SYNCGROUPID_ActiveParamChanged =
12975 {
12976 "ActiveParamChanged",
12977  {
12978  {SYNCITEM_ActiveParamChanged_GridMode, "GridMode"},
12979  {SYNCITEM_ActiveParamChanged_ScaleDimValues, "ScaleDimValues"},
12980  {SYNCITEM_ActiveParamChanged_ScaleAnnotations, "ScaleAnnotations"},
12981  {SYNCITEM_ActiveParamChanged_ScaleMlineOffsets, "ScaleMlineOffsets"},
12982  {SYNCITEM_ActiveParamChanged_GridRef, "GridRef"},
12983  {SYNCITEM_ActiveParamChanged_TagIncrement, "TagIncrement"},
12984  {SYNCITEM_ActiveParamChanged_KeyPoint, "KeyPoint"},
12985  {SYNCITEM_ActiveParamChanged_SnapOverride, "SnapOverride"},
12986  {SYNCITEM_ActiveParamChanged_Nextggroup, "Nextggroup"},
12987  {SYNCITEM_ActiveParamChanged_Numscreens, "Numscreens"},
12988  {SYNCITEM_ActiveParamChanged_Fence, "Fence"},
12989  {SYNCITEM_ActiveParamChanged_FenceView, "FenceView"},
12990  {SYNCITEM_ActiveParamChanged_GridOrientation, "GridOrientation"},
12991  {SYNCITEM_ActiveParamChanged_SnapMode, "SnapMode"},
12992  {SYNCITEM_ActiveParamChanged_CelllibFilename, "CelllibFilename"},
12993  {SYNCITEM_ActiveParamChanged_LevelFilter, "LevelFilter"},
12994  {SYNCITEM_ActiveParamChanged_GridUnits, "GridUnits"},
12995  {SYNCITEM_ActiveParamChanged_UnitRoundoff, "UnitRoundoff"},
12996  {SYNCITEM_ActiveParamChanged_StreamDelta, "StreamDelta"},
12997  {SYNCITEM_ActiveParamChanged_StreamTolerance, "StreamTolerance"},
12998  {SYNCITEM_ActiveParamChanged_StreamAngle, "StreamAngle"},
12999  {SYNCITEM_ActiveParamChanged_StreamArea, "StreamArea"},
13000  {SYNCITEM_ActiveParamChanged_AxisAngle, "AxisAngle"},
13001  {SYNCITEM_ActiveParamChanged_AxisOrigin, "AxisOrigin"},
13002  {SYNCITEM_ActiveParamChanged_GridAngle, "GridAngle"},
13003  {SYNCITEM_ActiveParamChanged_DimCompat, "DimCompatibility"},
13004  {SYNCITEM_ActiveParamChanged_MlineCompat, "MlineCompatibility"},
13005  {SYNCITEM_ActiveParamChanged_LevelUsage, "LevelUsage"},
13006  }
13007 };
13008 // Maximum of 32 SyncItems per group
13009 SyncGroupRsc SYNCGROUPID_ModelParamChanged =
13010 {
13011 "ModelParamChanged",
13012  {
13013  {SYNCITEM_ModelParamChanged_UnitRoundRatio, "UnitRoundRatio"},
13014  {SYNCITEM_ModelParamChanged_SubPerMaster, "SubPerMaster"},
13015  {SYNCITEM_ModelParamChanged_UorPerSub, "UorPerSub"},
13016  {SYNCITEM_ModelParamChanged_MasterUnitLabel, "MasterUnitLabel"},
13017  {SYNCITEM_ModelParamChanged_SubUnitLabel, "SubUnitLabel"},
13018  {SYNCITEM_ModelParamChanged_UorPerMaster, "UorPerMaster"},
13019  {SYNCITEM_ModelParamChanged_GlobalOrigin, "GlobalOrigin"},
13020  {SYNCITEM_ModelParamChanged_GridRatio, "GridRatio"},
13021  }
13022 };
13023 SyncGroupRsc SYNCGROUPID_TextParamChanged =
13024 {
13025 "TextParamChanged",
13026  {
13027  {SYNCITEM_TextParamChanged_Font, "Font"},
13028  {SYNCITEM_TextParamChanged_TextJust, "TextJust"},
13029  {SYNCITEM_TextParamChanged_NodeJust, "NodeJust"},
13030  {SYNCITEM_TextParamChanged_LineLength, "LineLength"},
13031  {SYNCITEM_TextParamChanged_Tab, "Tab"},
13032  {SYNCITEM_TextParamChanged_NextTextnode, "NextTextnode"},
13033  {SYNCITEM_TextParamChanged_FontName, "FontName"},
13034  {SYNCITEM_TextParamChanged_TextStyle, "TextStyle"},
13035  {SYNCITEM_TextParamChanged_TextHeight, "TextHeight"},
13036  {SYNCITEM_TextParamChanged_TextWidth, "TextWidth"},
13037  {SYNCITEM_TextParamChanged_LineSpacing, "LineSpacing"},
13038  {SYNCITEM_TextParamChanged_TextSlant, "TextSlant"},
13039  }
13040 };
13041 
13042 @endcode
13043 
13044 <H3>Using Sync Events in your WPF ViewModels</H3>
13045 <P>Example of a ViewModel that is interested in monitoring ActiveModelChanges in MicroStation. </P>
13046 
13047 @code{.unparsed}
13048 internal class ExampleViewModel : Bentley.MstnPlatformNET.Ribbon.ViewModels.RibbonItemViewModel
13049 {
13050 UISyncInterest m_ActiveModelChangedInterests;
13051 public ExampleViewModel()
13052  {
13053  UISyncInterestList refreshMasks = new UISyncInterestList ();
13054  refreshMasks.AddSyncInterest (m_ActiveModelChangedInterests = UMDialogManager.GetSyncInterest ("SystemEvent.ActiveModelChanged"));
13055  SyncInterestList = refreshMasks;
13056  }
13057 
13058 public override void OnUserInterfaceSyncEvent (System.UInt32[] eventMasks)
13059  {
13060  if (m_ActiveModelChangedInterests.IsSpecifiedInEventMasks (eventMasks))
13061  Refresh();
13062  }
13063 public override void Refresh ()
13064  {
13065  if (null != VisibilitySpec)
13066  Visibility = VisibilitySpec.IsVisible () ? System.Windows.Visibility.Visible : System.Windows.Visibility.Collapsed;
13067  else
13068  Visibility = System.Windows.Visibility.Visible;
13069  if (this is ISupportsEnableExpression)
13070  {
13071  ISupportsEnableExpression supportsEnableExpression = this as ISupportsEnableExpression;
13072  if (!String.IsNullOrWhiteSpace (supportsEnableExpression.EnableExpression))
13073  IsEnabled = Bentley.Internal.MstnPlatformNET.NamedExpressionManager.EvaluateAsCriteria (supportsEnableExpression.EnableExpression, null, false);
13074  }
13075  }
13076 }
13077 
13078 @endcode
13079 
13080 <H3>Application Provided Sync Group Resources </H3>
13081 <P>Applications that want to add their own sync events can do so. The steps involved are the following:</P>
13082 
13083 <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>
13084  <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>
13085 
13086 @code{.unparsed}
13087 
13088  <Part Name="myapp" BMakeFile="apps\myapp.mke">
13089  <Bindings>
13090  <Files ProductDirectoryName="MdlsysAsneeded">
13091  Delivery\myapp.ma
13092  <TransKit SourceDirectory="Delivery\TransKit\MdlApps\myapp" />
13093  <LoadConfig AppName="myapp" ConfigVars="MS_CMDTABLE_LOAD,MS_SYNCGROUP_APPS" />
13094  </Files>
13095  </Bindings>
13096  </Part>
13097 
13098 @endcode
13099 
13100  <Li>See test application ..\MstnPlatform\mstn\testapps\RibbonTestApp for example of setting up and firing Application provided Sync Events. </LI>
13101 
13102 </OL>
13103 
13104 <H3>ContextualTabSet definition </H3>
13105 
13106 <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>
13107 
13108 @code{.unparsed}
13109 
13110 
13111  <ContextualTabSets>
13112  <!?Example that activates/deactivates a contextual tab based on the selected element -->
13113  <ContextualTabSet Name="Mstn.TabSet.Table" Color="Coral" SelectFirstTabOnActivation="false">
13114  <Label>Table Tools</Label>
13115  <TabSetParams>
13116  <SyncItemEvent>SystemEvent.SelectionSetChanged</SyncItemEvent>
13117  <Visibility>
13118  <ShowExpression>[Selection](Selection.ContainsSingleElement() AND Selection.ContainsText() AND Selection.OnlyContainsActiveModelElements())</ShowExpression>
13119  <FeatureAspect></FeatureAspect>
13120  </Visibility>
13121  </TabSetParams>
13122  <ContextualTabs>
13123  <TabRef Name="DrawingTasks" Priority="10">
13124  <TabParams>
13125  <AccessText>TD</AccessText>
13126  </TabParams>
13127  </TabRef>
13128  </ContextualTabs>
13129  </ContextualTabSet>
13130 
13131  <!?Example that activates/deactivates a contextual tab based on a key. This would be useful during tool processing -->
13132  <ContextualTabSet Name="Mstn.Context.Drawing" Color="Coral" SelectFirstTabOnActivation="false">
13133  <Label>Drawing Tools</Label>
13134  <TabSetParams>
13135  <SyncItemEvent>SystemEvent.ContextualTabKeyChanged</SyncItemEvent>
13136  <Visibility>
13137  <ShowExpression>[Session](Session.IsContextualTabKeyActive("DrawingTest"))</ShowExpression>
13138  <FeatureAspect></FeatureAspect>
13139  </Visibility>
13140  </TabSetParams>
13141  <ContextualTabs>
13142  <TabRef Name="DrawingTasks" Priority="10">
13143  <TabParams>
13144  <AccessText>TD</AccessText>
13145  </TabParams>
13146  </TabRef>
13147  </ContextualTabs>
13148  </ContextualTabSet>
13149  </ContextualTabSets>
13150 
13151 @endcode
13152 
13153 <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>
13154 
13155 <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>
13156  <LI>DialogManager::DeactivateContextualTabSet (WCharCP key).</LI>
13157  <LI>DialogManager::ClearAllContextualTabSetKeys () </LI>
13158 </UL>
13159 
13160 <P><B>Managed API</B> - wrapper around native methods shown above. </P>
13161 
13162 <UL> <LI>ActivateContextualTabSet (string key);</LI>
13163  <LI>DeactivateContextualTabSet (string key);</LI>
13164  <LI>ClearAllContextualTabSetKeys (); </LI>
13165 </UL>
13166 <H2>Telerik RadRibbonView</H2>
13167 <H3>RadRibbonView Features </H3>
13168 
13169 <P>The RadRibbonView control has these key features: </P>
13170 
13171 <UL>
13172 <LI>MS Office 2010 Interface </LI>
13173 <LI>Automatic Resizing & Minimization </LI>
13174 <LI>Tabs, Groups, Galleries, Popups, Dialog Launcher </LI>
13175 <LI>Backstage Menu & Application Menu </LI>
13176 <LI>Buttons - Combo, Split, DropDown, Radio, Toggle </LI>
13177 <LI>Screen Tips </LI>
13178 <LI>Key Tips </LI>
13179 <LI>Styling and Appearance </LI>
13180 <LI>Expression Blend Support </LI>
13181 </UL>
13182 
13183 <H3>More Ribbon Related Controls </H3>
13184 
13185 <P>The "RadControls for WPF" suite contains several class related to the Ribbon: </P>
13186 
13187 <UL>
13188 <LI>RadRibbonWindow </LI>
13189 <LI>RadRibbonView </LI>
13190 <LI>Classes with the RadRibbon prefix
13191 <UL><LI>Tab </Li>
13192  <LI>Group </LI>
13193  <LI>Gallery </LI>
13194  <LI>Button </LI>
13195  <LI>ComboBox </LI>
13196  <LI>DropDownButton </LI>
13197  <LI>SplitButton </LI>
13198  <LI>RadioButton </LI>
13199  <LI>ToggleButton </LI></UL>
13200 </LI>
13201 <Li>Other Classes used with the Ribbon
13202 <UL><LI>ApplicationMenu </LI>
13203  <LI>QuickAccessToolbar </LI>
13204  <LI>StackPanel </LI>
13205  <LI>Separator </LI></UL>
13206 </LI>
13207 <LI>Layout Classes for the Ribbon
13208 <UL><LI>RadOrderedWrapPanel </LI>
13209  <LI>RadCollapsiblePanel </LI></UL>
13210 </LI>
13211 <LI>RadRibbonBar (deprecated) - superseded by RadRibbonView </LI>
13212 </UL>
13213 
13214 <H3>Ribbon Events </H3>
13215 
13216 <UL>
13217 <LI>RadRibbonView
13218 <UL><LI>ApplicationButtonDoubleClick </LI>
13219  <LI>ApplicationMenuOpenStateChanged </LI>
13220  <LI>ToolBarPositionChanged </LI>
13221  <LI>HelpRequested </LI>
13222  <LI>CollapsedChanged </LI></UL>
13223 </LI>
13224 <LI>Selection
13225 <UL><LI>PreviewSelectionChanged </LI>
13226  <LI>SelectionChanged </LI></UL>
13227 </LI>
13228 <LI> Minimization
13229 <UL><LI>MinimizedChanged</LI>
13230  <LI>MinimizedPopupOpenStateChanged </LI>
13231  <LI>PreviewPopupOpened </LI>
13232  <LI>PopupOpened </LI></UL>
13233 </LI>
13234 <LI>RadGallery
13235 <UL><LI>ActionPreview </LI>
13236  <LI>DeactivatePreview </LI></UL>
13237 </LI>
13238 <LI>RadRibbonGroup
13239 <UL><LI>LauchDialog </LI></UL>
13240 </LI>
13241 </UL>
13242 
13243 <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>
13244 
13245 
13246 
13247 
13248 
13249 @addtogroup CommandFrameworkAndXCommands
13250 
13251 @note XCommands are Cross-UI-Platform Command definitions that can be used by the Ribbon, Menus and XCmdButtons.
13252 
13253 <P>User Interface Development Index: BSWUserInterfaceDevelopment
13254 
13255 <H2>Legacy Command Support </H2>
13256 
13257 <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>
13258 
13259 
13260 <H3>Command Tables</H3>
13261 
13262 <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>
13263 
13264 <P>This is an example command definition from cmdtable.r in the PowerPlatform core: </P>
13265 
13266 @code{.unparsed}
13267 
13268  #define CT_NONE 0
13269  #define CT_MAIN 1
13270  #define CT_DIALOG 228
13271  . . .
13272 
13273  CommandTable CT_MAIN =
13274  {
13275  . . .
13276  {119, CT_DIALOG, DIALOGOPEN, TRY|IMM, "DIALOG" },
13277  . . .
13278 
13279  CommandTable CT_DIALOG =
13280  {
13281  . . .
13282  { 68, CT_NONE, INHERIT, NONE, "OPENFILE", 580, },
13283  . . .
13284 
13285 @endcode
13286 
13287 <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.
13288 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>
13289 
13290 <P>Example CommandNumbers from the generated cmdlist.r.h command number header file: </P>
13291 
13292 @code{.unparsed}
13293 
13294  #define CMD_DIALOG_OPENFILE 0x7744000000000000UI64 /* DIALOGOPEN CmdString = 580 */
13295 @endcode
13296 
13297 <P>Example command function setup: </P>
13298 
13299 @code{.unparsed}
13300  static void myapp_openFile (WCharCP unparsedCP)
13301  {
13302  }
13303  . . .
13304  static MdlCommandNumber commandNumber[] =
13305  {
13306  {myapp_openFile, CMD_DIALOG_OPENFILE },
13307  0
13308  };
13309  . . .
13310  extern "C" void MdlMain (int argc, WCharCP argv[])
13311  {
13312  mdlSystem_registerCommandNumbers (commandNumber);
13313 
13314 @endcode
13315 
13316 <P>To be thorough and not short change .NET AddIns, here is an example setup for AddIn commands:</P>
13317 
13318 @code{.unparsed}
13319 
13320  -- XML File --
13321 
13322  <?xml version="1.0" encoding="utf-8" ?>
13323  <KeyinTree xmlns="http://www.bentley.com/schemas/1.0/MicroStation/AddIn/KeyinTree.xsd">
13324  <RootKeyinTable ID="root">
13325  <Keyword SubtableRef="props" CommandClass="MacroCommand" CommandWord="MSGCENTER">
13326  <Options Required="true"/>
13327  </Keyword>
13328  </RootKeyinTable>
13329 
13330  <SubKeyinTables>
13331  <KeyinTable ID="props">
13332  <Keyword CommandWord="OPEN" />
13333  . . .
13334  </KeyinTable>
13335  </SubKeyinTables>
13336 
13337  <KeyinHandlers>
13338  <KeyinHandler Keyin="MSGCENTER OPEN" Function="MsgCenter.MessageCenterApp.Open" />
13339  . . .
13340  </KeyinHandlers>
13341  </KeyinTree>
13342 
13343  -- C# File --
13344 
13345  namespace MsgCenter
13346  {
13347  [Bentley.MstnPlatformNET.AddInAttribute(MdlTaskID = "MsgCenter")]
13348  public sealed class MessageCenterApp : Bentley.MstnPlatformNET.AddIn
13349  {
13350  . . .
13351  /*------------------------------------------------------------------------------------**/
13353  /*--------------+---------------+---------------+---------------+---------------+------*/
13354  public static void Open
13355  (
13356  string unparsed
13357  )
13358  {
13359  MainWindow.OpenWindow();
13360  }
13361 @endcode
13362 
13363 <H3>IconCmds and Menus</H3>
13364 
13365 <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>
13366 
13367 <UL> <LI>CommandNumber </LI>
13368  <LI>Task ID </LI>
13369  <LI>Unparsed string containing command parameters </LI>
13370  <LI>Attributes</LI>
13371  <LI>Balloon (tooltip) text</LI>
13372  <LI>Flyover text, which is more descriptive than the tooltip text and is displayed in the Status Bar on hover</LI>
13373  <LI>Small and Large icon information</LI>
13374 </UL>
13375 
13376 <P>An example of an IconCmd using the CMD_DIALOG_OPENFILE CommandNumber: </P>
13377 
13378 @code{.unparsed}
13379  DItem_IconCmdRsc ICONCMDID_OpenFile =
13380  {
13381  NOHELP, MHELPTASKIDCMD, 0,
13382  CMD_DIALOG_OPENFILE, MTASKID, "",
13383  ""
13384  }
13385  extendedAttributes
13386  {{
13387  {EXTATTR_FLYTEXT, TXT_Flyover_OpenFile},
13388  {EXTATTR_BALLOON, TXT_Balloon_OpenFile}
13389  }};
13390 
13391  IconCmdSmallRsc ICONCMDID_OpenFile =
13392  {
13393  24, 24, ICONFORMAT_WINDOWS, BLACK_INDEX, "Open File", "FileOpen"
13394  };
13395 
13396  IconCmdLargeRsc ICONCMDID_OpenFile =
13397  {
13398  32, 32, ICONFORMAT_WINDOWS, BLACK_INDEX, "Open File", "FileOpen"
13399  };
13400 
13401 @endcode
13402 
13403 <P>Menu items contain information similar to IconCmds, but with a few additions: </P>
13404 
13405 <UL><LI>Label </LI>
13406  <LI>Accelerator key combination</LI>
13407  <LI>Hook information </LI>
13408  <LI>Search Id </LI>
13409  <LI>CommandNumber </LI>
13410  <LI>Task Id</LI>
13411  <LI>Unparsed string containing command parameters </LI>
13412  <LI>A reference to an IconCmd to get the icon information</LI>
13413 
13414 </UL>
13415 
13416 <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>
13417 
13418 <P>An example of a menu item using the CMD_DIALOG_OPENFILE CommandNumber: </P>
13419 
13420 @code{.unparsed}
13421 
13422  @if (FeatureAspect (PP_ID_FeatureAspects_File_Open)) // @fadoc File | Open menu item
13423  {TXT2_FileOpenOption, 'O'|VBIT_CTRL, ON, NOMARK, 0, NOSUBMENU,
13424  HELPID_PULLDOWN_FileOpen, MHELPTASKIDTOPIC,
13425  NOHOOK, MENUSEARCHID_File_Open,
13426  CMD_DIALOG_OPENFILE, MTASKID, "",
13427  ICONCMDID_OpenFile, Icon, MTASKID},
13428  @endif
13429 
13430 @endcode
13431 
13432 <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>
13433 
13434 <UL><LI>Name / Id </LI>
13435  <LI>CommandNumber </LI>
13436  <LI>Task ID </LI>
13437  <LI>Unparsed string containing command parameters </LI>
13438  <LI>Icon </LI>
13439  <LI>Title / Label </LI>
13440  <LI>Description </LI>
13441  <LI>Feature Tracking Id (cross-referenced to Help Id)</LI>
13442  <LI>Show/Hide Expression </LI>
13443  <LI>Enable/Disable Expression </LI>
13444  <LI>Toggle Expression </LI>
13445  <LI>Menu Mark Expression </LI>
13446  <LI>Accelerator </LI>
13447  <LI>Feature Aspect Id </LI>
13448 </UL>
13449 
13450 <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>
13451 
13452 <P>The XCommand structures in dialogbox.r.h: </P>
13453 
13454 @code{.unparsed}
13455 
13456  typedef struct xcommandrsc
13457  {
13458  char name[];
13459  CommandRsc command;
13460  char iconName[];
13461  Utf8Char title[];
13462  Utf8Char description[];
13463  char featureTrackingId[];
13464  char showExpression[];
13465  char enableExpression[];
13466  char toggleExpression[];
13467  char markExpression[];
13468  char uiSynchEvents[];
13469  UInt32 accelerator;
13470  UInt32 featureAspectId;
13471  } XCommandRsc;
13472 
13473  typedef struct commandrsc
13474  {
13475  CommandNumber commandNumber;
13476  char commandTaskId[];
13477  char unparsed[];
13478  } CommandRsc;
13479 
13480 @endcode
13481 
13482 <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>
13483 
13484 @code{.unparsed}
13485 
13486  XCommandListRsc XCMDLISTID_MstnPlatform =
13487  {
13488  {
13489  . . .
13490  {"Mstn.File.Open", // File Open Dialog
13491  {CMD_DIALOG_OPENFILE, MTASKID, ""},
13492  "Open",
13493  TXT_Balloon_OpenFile,
13494  TXT_Flyover_OpenFile,
13495  "ec375142-3726-11e3-bf6e-6894231a2840",
13496  "", "", "", "", "",
13497  'O'|VBIT_CTRL,
13498  PP_ID_FeatureAspects_File_Open}, // @fadoc Mstn.File.Open XCommand
13499  . . .
13500  }
13501  };
13502 
13503 @endcode
13504 @note The Feature Tracking Id is a GUID and must be unique.
13505 
13506 <H3>XCmdButton</H3>
13507 <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>
13508 
13509 <P>The XCmdButton structures in dlogbox.r.h: </P>
13510 
13511 @code{.unparsed}
13512 
13513  typedef struct ditem_xcmdbuttonrsc
13514  char xCommandName[];
13515  long itemHookId;
13516  UInt64 itemHookArg;
13517  UInt32 attributes;
13519 @endcode
13520 
13521 <P>An example of an XCmdButton in a .r file: </P>
13522 
13523 @code{.unparsed}
13524 
13525  // Definition --
13527  {
13528  "Mstn.File.Open", 0, 0, 0
13529  };
13530 
13531  // Reference --
13532  {{ 0, 0, 0, 0}, XCmdButton, ICONCMDID_OpenFile, ON, 0, "", ""},
13533 
13534 @endcode
13535 
13536 <H3>PartFile and MS_XCOMMAND_APPS </H3>
13537 
13538 <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>
13539 
13540 <P>An example of including MX_XCOMMAND_APPS in the ConfigVars attribute of the <LoadConfig> element: </P>
13541 
13542 @code{.unparsed}
13543 
13544  <Part Name="MdlApp-2ddraw" BMakeFile="apps\2ddraw\2ddraw.mke">
13545  <SubPart PartName="2dModelingDll" />
13546  <Bindings>
13547  <Files ProductDirectoryName="MdlsysAsneeded" FeatureAspect="PP_ID_FeatureAspects_BaseGeometry">
13548  Delivery\2ddraw.ma
13549  <TransKit SourceDirectory="Delivery\TransKit\MdlApps\2dModeling\2ddraw" />
13550  <LoadConfig AppName="2ddraw" ConfigVars="MS_CMDTABLE_LOAD,MS_XCOMMAND_APPS" />
13551  </Files>
13552  </Bindings>
13553  </Part>
13554 
13555 @endcode
13556 
13557 <H3>Native API </H3>
13558 
13559 <P>The native API for XCommands is in the following interface and classes: </P>
13560 
13561 <UL><LI>IXCommand - native interface for Cross UI Framework PowerPlatform Command </LI>
13562  <LI>XCommand - native class and implementation of IXCommand </LI>
13563  <LI>XCommandManager - manager and caching class for XCommands</LI>
13564 </UL>
13565 
13566 <P>The following is an example of using the native XCommand API to activate/execute a command: </P>
13567 
13568 @code{.unparsed}
13569 
13570  #include <Mstn\XCommand.h>
13571  #include <Mstn\XCommandManager.h>
13572  . . .
13573  IXCommandP xCommandP;
13574 
13575  xCommandP = XCommandManager::GetManager().FindXCommand (L"Mstn.File.Open");
13576 
13577  if (NULL != xCommandP)
13578  xCommand->ExecuteCmd (NULL, NULL);
13579 
13580 @endcode
13581 
13582 <H2>The Ribbon and XCommands </H2>
13583 
13584 <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>
13585 
13586 <H3>ICommand and RelayCommand </H3>
13587 
13588 <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>
13589 
13590 <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>
13591 
13592 <H3>IMstnCommand and NamedMstnCommand </H3>
13593 
13594 <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>
13595 
13596 <UL><LI>bool CanExecute</LI>
13597  <LI>bool CanDisplay </LI>
13598  <LI>String IconName </LI>
13599  <LI>BMG::RscIconSpec IconSpec </LI>
13600  <LI>String Label </LI>
13601  <LI>String Description </LI>
13602  <LI>String AcceleratorString </LI>
13603 </UL>
13604 
13605 <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>
13606 
13607 <H3>MstnRelayCommand </H3>
13608 
13609 <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>
13610 
13611 <UL><LI>MstnRelayCommand ( BM.Commands.IMstnCommand)</LI>
13612  <LI>bool CanDisplay </LI>
13613  <LI>SW.Visibility Visibility</LI>
13614  <LI>ImageSource SmallImage </LI>
13615  <LI>ImageSource LargeImage </LI>
13616  <LI>String Label </LI>
13617  <LI>String Description </LI>
13618  <LI>String AcceleratorString</LI>
13619  <LI>BMC::IMstnCommand Command </LI>
13620  <LI>bool CanExecute () (from ICommand)</LI>
13621  <LI>Execute() (from ICommand)</LI>
13622  <LI>CanExecuteChanged event (from ICommand)</LI>
13623 </UL>
13624 
13625 <H3>Ribbon Definitions </H3>
13626 
13627 <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>
13628 
13629 <P>An example of a <Button> element in an XML file: </P>
13630 
13631 @code{.unparsed}
13632 
13633  <Buttons>
13634  <Button Name="Mstn.File.Open" Priority="0">
13635  <ButtonData>
13636  <CommandData Type="NamedCommand">
13637  <NamedCommand>Mstn.File.Open</NamedCommand>
13638  </CommandData>
13639  </ButtonData>
13640  </Button>
13641  . . .
13642  </Buttons>
13643 
13644 @endcode
13645 
13646 <P>An example of a <ButtonRef> element referring to a Named <Button> in an XML file: </P>
13647 
13648 @code{.unparsed}
13649 
13650  <QuickAccessCollections>
13651  <QuickAccessCollection Name="Mstn.QuickAccessItems" . . .
13652 
13653  <ButtonRef Name="Mstn.File.Open" Priority="5">
13654  <ButtonParams Size="Small" CollapseToSmall="Never" CollapseToMedium="Never">
13655  <AccessText>2</AccessText>
13656  </ButtonParams>
13657  </ButtonRef>
13658  . . .
13659 @endcode
13660 
13661 <H3>Using NamedMstnCommands and MstnRelayCommands in C# and XAML </H3>
13662 
13663 <P>An example of exposing an XCommand to C# or XAML via the NamedMstnCommand and MstnRelayCommand classes: </P>
13664 
13665 @code{.unparsed}
13666  -- MyCommands.cs --
13667 
13668  using BM = Bentley.MstnPlatformNET;
13669 
13670  class MyCommands
13671  {
13672  private MstnRelayCommand m_FileOpen;
13673  public MstnRelayCommand FileOpen
13674  {
13675  get
13676  {
13677  if (m_FileOpen == null)
13678  m_FileOpen = new MstnRelayCommand(new BM.Commands.NamedMstnCommand ("Mstn.File.Open"));
13679  return m_FileOpen;
13680  }
13681  }
13682 
13683  -- MyViewModel.cs --
13684 
13685  public MyCommands MyCommands;
13686 
13687 @endcode
13688 
13689 <P>An example of referencing an MstnRelayCommand in XAML for the Backstage: </P>
13690 
13691 @code{.unparsed}
13692  -- MyView.xaml --
13693 
13694  xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"
13695 
13696  <telerik:RadRibbonBackstageItem Header="{x:Static props:Resources.Open_Label}"
13697  IsSelectable="False"
13698  CloseOnClick="True"
13699  Command="{Binding MyCommands.FileOpen}"
13700  Visibility="{Binding MyCommands.FileOpen.Visibility}"
13701  telerik:KeyTipService.AccessText="O"/>
13702 
13703 
13704 @endcode
13705 
13706 <H3>XCommands for .NET AddIns </H3>
13707 
13708 <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>
13709 
13710 <OL>
13711 <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:
13712 @code{.unparsed}
13713 
13714  #include <Mstn\MicroStation.r.h>
13715  #include <Mstn\MdlApi\dlogbox.r.h>
13716 
13717  #include <ribbontext.h>
13718  #include <rsrctxt2.h>
13719 
13720  #include <TransKitGenSrc\bentley.ecuisupportcmd.h>
13721  #include <TransKitGenSrc\PowerPlatform.FeatureAspects.h>
13722 
13723  XCommandListRsc 1 =
13724  {
13725  {
13726  {"Mstn.File.Properties",
13727  {CMD_ELEMENT_INFO_FILEPROPERTIES, "Bentley.ECUISupport", ""},
13728  "Properties",
13729  TXT_RibbonLabel_FileProperties,
13730  TXT_RibbonDesc_FileProperties,
13731  "ec383b8d-3726-11e3-8f85-6894231a2840", "", "", "", "", "", NOACCEL,
13732  PP_ID_FeatureAspects_File_Properties}, // @fadoc File.Properties XCommand
13733  {"Mstn.ProjectNavigation.Explorer",
13734  {CMD_DIALOG_EXPLORER_TOGGLE, "Bentley.ECUISupport", ""},
13735  "ProjectExplorer",
13736  TXT2_FileProjectOption,
13737  TXT_RibbonDesc_Explorer,
13738  "ec3a104e-3726-11e3-a7ad-6894231a2840", "", "", "", "", "", NOACCEL,
13739  PP_ID_FeatureAspects_Properties_ECBrowser}, // @fadoc ProjectNavigation.Explorer XCommand
13740 
13741  }
13742  };
13743 
13744 @endcode
13745 
13746 <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>
13747 <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>
13748 <P>The "#include <TransKitGenSrc\bentley.ecuisupportcmd.h>" and CMD_ELEMENT_INFO_FILEPROPERTIES sections are related to step 4 below.</P></LI>
13749 
13750 <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:
13751 
13752 @code{.unparsed}
13753 
13754  <?xml version="1.0" encoding="utf-8"?>
13755 
13756  <Transkit>
13757 
13758  <SatelliteAssembly DllName="Bentley.ECUISupport" DeliverEnglish="False" RightsCompliant="True">
13759  <ResxFile ResourceName="Bentley.ECUISupport" FileName="ECUISupport.resx" />
13760  </SatelliteAssembly>
13761 
13762  <BentleyRsc Name="Bentley.ECUISupport.rsc.mui" >
13763  <ResourceSource>Bentley.ECUISupport.r</ResourceSource>
13764  </BentleyRsc>
13765  </Transkit>
13766 
13767 @endcode
13768 </LI>
13769 
13770 <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>
13771 
13772 @code{.unparsed}
13773 
13774  <Part Name="ClrApp-ECUISupport" BMakeFile="mstn\clrapps\ECUISupport\ECUISupport.mke">
13775  <SubPart PartName="DgnDisplayNet" PartFile="DgnDisplayNet" Repository="DgnDisplayNet" />
13776  <SubPart PartName="ClrApp-propertymanager" />
13777  <SubPart PartName="Componentsets" PartFile="PPModules\Componentsets\Componentsets" />
13778  <Bindings>
13779  <Assemblies ProductDirectoryName="PPManagedAssemblies">
13780  Delivery\Bentley.ECUISupport.dll
13781  Delivery\Bentley.ECUISupport.rsc
13782  <TransKit SourceDirectory="Delivery\TransKit\clrapps\Bentley.ECUISupport" />
13783  <LoadConfig AppName="Bentley.ECUISupport" ConfigVars="MS_CMDTABLE_LOAD,MS_XCOMMAND_RSCS" />
13784  </Assemblies>
13785  </Bindings>
13786  </Part>
13787 
13788 @endcode
13789 
13790 <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:
13791 
13792 @code{.unparsed}
13793 
13794  #----------------------------------------------------------------------
13795  # Create the command table include file.
13796  #----------------------------------------------------------------------
13797  $(gensrcTransKit)$(appName)cmd.h : $(baseDir)src/Resources/ECUISupport.commands.xml
13798 
13799 @endcode
13800 
13801 <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>
13802 </LI>
13803 
13804 <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.
13805 
13806 @code{.unparsed}
13807 
13808 #----------------------------------------------------------------------
13809 # Create and SymLink the XCommand .rsc file
13810 #----------------------------------------------------------------------
13811 MuiBaseName = $(appName).rsc
13812 MuiTranskitDeliveryDir = $(ContextDeliveryDir)TransKit/clrapps/$(appName)/
13813 MuiAdditionalIncludes = $(MSCore)TransKit/SharedInc/ $(gensrc)
13814 MuiTranskitSourceDir = $(baseDir)src/Resources/
13815 
13816 # This tells CreateAndSymLinkMui to symlink the resource file itself
13817 ForClrAppXCommand = 1>
13818 
13819 # This tells CreateAndSymLinkMui to avoid symlinking the transkit.xml file - SymLinkResxTrankitFiles.py does that.
13820 DontSymLinkTranskitXml = 1
13821 
13822 %include $(SharedMki)CreateAndSymlinkMui.mki
13823 
13824 @endcode
13825 
13826 <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>
13827 </LI>
13828 </OL>
13829 <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>
13830 
13831 
13832 
13833 @addtogroup IRibbonComponentProviders
13834 
13835 @note IRibbonComponentProviders provide component that can be placed on the Ribbon in MicroStation
13836 
13837 <H2>IRibbonComponentProviders </H2>
13838 
13839 <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>
13840 
13841 @code{.unparsed}
13842 
13843  RibbonComponentManager.Manager.RegisterRibbonComponentProvider (new RibbonComponentProvider ());
13844 
13845 @endcode
13846 
13847 <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>
13848 <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>
13849 
13850 <table>
13851 <tr>
13852 <th>Component Type</th> <th>Definition Type</th> <th>ViewModel Type</th> <th>Control Type</th>
13853 </tr>
13854 <tr>
13855 <td>Tab</td> <td>RibbonTabDefinition</td> <td>RibbonTabViewModel</td> <td>RadRibbonTab</td>
13856 </tr>
13857 <tr>
13858 <td>Group </td> <td>RibbonGroupDefinition </td> <td>RibbonGroupViewModel </td> <td>RadRibbonGroup</td>
13859 </tr>
13860 <tr>
13861 <td>Panel </td> <td>RibbonGroupPanelDefinition </td> <td>RibbonGroupPanelViewModel </td> <td>StackPanel,RadCollapsiblePanel, or RadOrderedWrapPanel </td>
13862 </tr>
13863 <tr>
13864 <td>ButtonGroup </td> <td>RibbonButtonGroupDefinition </td> <td>RibbonButtonGroupViewModel</td> <td>RadButtonGroup </td>
13865 </tr>
13866 <tr>
13867 <td>Button </td> <td>RibbonButtonDefinition </td> <td>RibbonButtonViewModel </td> <td>RadRibbonButton </td>
13868 </tr>
13869 <tr>
13870 <td>DropDownButton </td> <td>RibbonDropDownButtonDefinition </td> <td> RibbonDropDownButtonViewModel </td> <td>RadRibbonDropDownButton </td>
13871 </tr>
13872 <tr>
13873 <td>SplitButton </td> <td>RibbonSplitButtonDefinition </td> <td> RibbonSplitButtonViewModel </td> <td>RadRibbonSplitButton </td>
13874 </tr>
13875 <tr>
13876 <td>ToggleButton </td> <td>RibbonToggleButtonDefinition </td> <td> RibbonToggleButtonViewModel </td> <td>RadRibbonToggleButton </td>
13877 </tr>
13878 <tr>
13879 <td>RadioButton </td> <td>RibbonRadioButtonDefinition </td> <td> RibbonRadioButtonViewModel </td> <td>RadRibbonRadioButton </td>
13880 </tr>
13881 <tr>
13882 <td>ComboBox </td> <td>RibbonComboBoxDefinition </td> <td> RibbonComboBoxViewModel </td> <td>RadRibbonComboBox </td>
13883 </tr>
13884 <tr>
13885 <td>Gallery </td> <td>RibbonGalleryDefinition </td> <td> RibbonGalleryViewModel </td> <td>RadRibbonGallery </td>
13886 </tr>
13887 </table>
13888 
13889 <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>
13890 <P>The Bentley.MstnPlatformNET.Ribbon.IRibbonComponentProvider interface definition is shown below: </P>
13891 
13892 @code{.unparsed}
13893 
13894  public interface IRibbonComponentProvider
13895  {
13897  String ProviderKey {get;}
13898 
13900  IList<RibbonTabCollectionDefinition> RegisterTabCollectionDefinitions ();
13901  IList<ContextualTabSetDefinition> RegisterContextualTabSetDefinitions ();
13902  IList<QuickAccessCollectionDefinition> RegisterQuickAccessCollectionDefinitions ();
13903  IList<RibbonButtonGroupDefinition> RegisterButtonGroupDefinitions ();
13904  IList<RibbonButtonDefinition> RegisterButtonDefinitions ();
13905  IList<RibbonDropDownButtonDefinition> RegisterDropDownButtonDefinitions ();
13906  IList<RibbonSplitButtonDefinition> RegisterSplitButtonDefinitions ();
13907  IList<RibbonToggleButtonDefinition> RegisterToggleButtonDefinitions ();
13908  IList<RibbonRadioButtonDefinition> RegisterRadioButtonDefinitions ();
13909  IList<RibbonComboBoxDefinition> RegisterComboBoxDefinitions ();
13910  IList<RibbonTabDefinition> RegisterTabDefinitions ();
13911  IList<RibbonMenuItemCollectionDefinition> RegisterMenuItemCollectionDefinitions ();
13912  IList<RibbonGroupPanelDefinition> RegisterGroupPanelDefinitions ();
13913  IList<RibbonGroupDefinition> RegisterGroupDefinitions ();
13914  IList<RibbonGalleryDefinition> RegisterGalleryDefinitions ();
13915  IList<WorkflowDefinition> RegisterWorkflowDefinitions ();
13916  IList<RibbonDropDownPanelDefinition> RegisterDropDownPanelDefinitions ();
13917  IList<BackstageItemDefinition> RegisterBackstageItemDefinitions ();
13918 
13922  ContextualTabSetViewModel CreateContextualTabSetViewModelFromDefinition (ContextualTabSetDefinition def);
13923  TabCollectionViewModel CreateTabCollectionViewModelFromDefinition (RibbonTabCollectionDefinition def);
13924  QuickAccessToolbarViewModel CreateQuickAccessCollectioniewModelFromDefinition (QuickAccessCollectionDefinition def);
13925  IRibbonItemViewModel CreateButtonGroupViewModelFromDefinition (RibbonButtonGroupDefinition def);
13926  IRibbonItemViewModel CreateButtonViewModelFromDefinition (RibbonButtonDefinition def);
13927  IRibbonItemViewModel CreateDropDownButtonViewModelFromDefinition (RibbonDropDownButtonDefinition def);
13928  IRibbonItemViewModel CreateSplitButtonViewModelFromDefinition (RibbonSplitButtonDefinition def);
13929  IRibbonItemViewModel CreateToggleButtonViewModelFromDefinition (RibbonToggleButtonDefinition def);
13930  IRibbonItemViewModel CreateRadioButtonViewModelFromDefinition (RibbonRadioButtonDefinition def);
13931  IRibbonItemViewModel CreateComboBoxViewModelFromDefinition (RibbonComboBoxDefinition def);
13932  IRibbonItemViewModel CreateTabViewModelFromDefinition (RibbonTabDefinition def);
13933  RibbonMenuItemCollectionViewModel CreateMenuItemCollectionViewModelFromDefinition (RibbonMenuItemCollectionDefinition def);
13934  IRibbonItemViewModel CreateGroupPanelViewModelFromDefinition (RibbonGroupPanelDefinition def);
13935  IRibbonItemViewModel CreateGroupViewModelFromDefinition (RibbonGroupDefinition def);
13936  IRibbonItemViewModel CreateGalleryViewModelFromDefinition (RibbonGalleryDefinition def);
13937  IRibbonItemViewModel CreateBackstageItemViewModelFromDefinition (BackstageItemDefinition def, ViewModelContext context);
13938 
13940  RadButtonGroup CreateButtonGroupFromViewModel (IRibbonItemViewModel item);
13941  RadRibbonButton CreateButtonFromViewModel (IRibbonItemViewModel item);
13942  RadDropDownButton CreateDropDownButtonFromViewModel (IRibbonItemViewModel item);
13943  RadRibbonSplitButton CreateSplitButtonFromViewModel (IRibbonItemViewModel item);
13944  RadRibbonToggleButton CreateToggleButtonFromViewModel (IRibbonItemViewModel item);
13945  RadRibbonRadioButton CreateRadioButtonFromViewModel (IRibbonItemViewModel item);
13946  RadRibbonComboBox CreateComboBoxFromViewModel (IRibbonItemViewModel item);
13947  RadRibbonTab CreateTabFromViewModel (IRibbonItemViewModel item);
13948  Object CreatePanelFromViewModel (IRibbonItemViewModel item);
13949  RadRibbonGroup CreateGroupFromViewModel (IRibbonItemViewModel item);
13950  RadRibbonGallery CreateGalleryFromViewModel (IRibbonItemViewModel item);
13951  RadRibbonBackstageItem CreateBackstageItemFromViewModel (IRibbonItemViewModel itemVm);
13952  }
13953 @endcode
13954 
13955 <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>
13956 
13957 <H3>Specifying Ribbon Component Providers</H3>
13958 
13959 <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>
13960 
13961 <H3>Example - Setting up a component provider </H3>
13962 
13963 @code{.unparsed}
13964 
13965  Addin Name:
13966  MyComponentProvider.dll
13967  cfg setting:
13968  MS_RIBBONCOMPONENTPROVIDERS < MyComponentProvider
13969 
13970  [Bentley.MstnPlatformNET.Ribbon.InstanceOnLoad]
13971  public class MyComponentProvider : Bentley.MstnPlatformNET.Ribbon.BaseRibbonComponentProvider
13972  {
13973  /*------------------------------------------------------------------------------------**/
13975  /*--------------+---------------+---------------+---------------+---------------+------*/
13976  public MyComponentProvider
13977  (
13978  )
13979  {
13980  RibbonComponentManager.Manager.RegisterRibbonComponentProvider (this)
13981  }
13982 
13983  /*------------------------------------------------------------------------------------**/
13985  /*--------------+---------------+---------------+---------------+---------------+------*/
13986  public override string ProviderKey
13987  {
13988  get {return "MyComponentProvider.RibbonComponentProvider"; }
13989  }
13990 
13991  /*------------------------------------------------------------------------------------**/
13993  /*--------------+---------------+---------------+---------------+---------------+------*/
13994  ~ MyComponentProvider() // destructor
13995  {
13996  RibbonComponentManager.Manager.UnRegisterRibbonComponentProvider (this.Name)
13997  }
13998 
13999  /*------------------------------------------------------------------------------------**/
14001  /*--------------+---------------+---------------+---------------+---------------+------*/
14002  public override IList<RibbonDropDownButtonDefinition> RegisterDropDownButtonDefinitions ()
14003  {
14004  ...
14005  }
14006 
14007  /*------------------------------------------------------------------------------------**/
14009  /*--------------+---------------+---------------+---------------+---------------+------*/
14010  public override IRibbonItemViewModel CreateDropDownButtonViewModelFromDefinition (RibbonDropDownButtonDefinition def)
14011  {
14012  switch (def.Name)
14013  {
14014  case "MyDropDownItem":
14015  {
14016  MyIRibbonItemVeiwModelBasedViewModel vm = new ....
14017 
14018  // set any specific property overrides from definition, like AccessText
14019  RibbonViewModelHelper.CopyPropertiesFromDefinition (vm, def);
14020 
14021  return vm;
14022  }
14023  }
14024  return null;
14025  }
14026 
14027  /*------------------------------------------------------------------------------------**/
14029  /*--------------+---------------+---------------+---------------+---------------+------*/
14030  public override RadDropDownButton CreateDropDownButtonFromViewModel (IRibbonItemViewModel itemVm)
14031  {
14032  switch (def.Name)
14033  {
14034  case "MyDropDownItem":
14035  {
14036  MyIRibbonItemVeiwModelBasedViewModel myVm = itemVm as MyIRibbonItemVeiwModelBasedViewModel;
14037 
14038  RadDropDownButton button = new MyDropDownButton (myVm); // button.DataContext should be set to your ViewModel (myVm)
14039 
14040  // set any specific overrides from definition, like AccessText and ToolTips
14041  RibbonComponentHelper.SetRadDropDownButtonPropertiesFromVM(button, itemVm);
14042 
14043  return button;
14044  }
14045  }
14046  return null;
14047  }
14048 @endcode
14049 
14050 <H3>Setting style to make Sure Your xaml supplied Tab, Groups and Buttons display </H3>
14051 <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>
14052 
14053 @code{.unparsed}
14054 
14055 [Bentley.MstnPlatformNET.AddInAttribute(MdlTaskID = "TableUI")]
14056 [ThemeStyle ("Bentley.TableUI", "Themes/Common.xaml")]
14057 public classTableUIApp : WpfAddIn
14058  {
14059 
14060 @endcode
14061 
14062 <P>Step 2. Define your styles in Common.xaml, below is an example.</P>
14063 
14064 @code{.unparsed}
14065 <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">
14066 <Style BasedOn="{StaticResource RadRibbonButtonStyle}" TargetType="{x:Type local:DistributeColumnsButton}"/>
14067 <Style BasedOn="{StaticResource RadRibbonButtonStyle}" TargetType="{x:Type local:DistributeRowsButton}"/>
14068 <Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableSymbologyGroup}"/>
14069 <Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableOptionsGroup}"/>
14070 <Style BasedOn="{StaticResource RadRibbonDropDownButtonStyle}" TargetType="{x:Type local:ShadingDropDownButton}"/>
14071 <Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableColorDropDownButton}" >
14072  <Setter Property="DropDownHeight"Value="450" /><Setter Property="DropDownWidth"Value="500" />
14073 </Style>
14074 <Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableLineStyleDropDownButton}" >
14075  <Setter Property="DropDownHeight"Value="500" /><Setter Property="DropDownWidth"Value="180" />
14076 </Style>
14077 <Style BasedOn="{StaticResource BentleyRibbonDropDownButtonStyle}" TargetType="{x:Type local:TableLineWeightDropDownButton}" >
14078  <Setter Property="DropDownHeight"Value="400" /><Setter Property="DropDownWidth"Value="170" />
14079 </Style>
14080 <Style BasedOn="{StaticResource RadRibbonSplitButtonStyle}" TargetType="{x:Type local:TableBordersSplitButton}"/>
14081 <Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:CellSizeGroup}"/>
14082 <Style BasedOn="{StaticResource RadRibbonGroupStyle}" TargetType="{x:Type local:TableSizeGroup}"/>
14083  </ResourceDictionary>
14084 @endcode
14085 
14086 <H3>Supporting RightClick HiddenTool Processing (and RibbonSearch support) </H3>
14087 
14088 <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>
14089 <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>
14090 
14091 <H3>Storing State Data for Ribbon Components </H3>
14092 
14093 <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>
14094 <OL>
14095 <LI>Define a class to get/set your state data properties. </LI>
14096 <LI>Define ECProperties within an ECClass that is uniquely named for your provider.</LI>
14097 <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>
14098 <LI>Set up C# Properties that get and set values in the instance specific to your provider.</LI>
14099 <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>
14100 
14101 
14102 <H3>Example - Defining Ribbon Component Provider State Data </H3>
14103 
14104 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>
14105 
14106 
14107 @code{.unparsed}
14108 
14109  /*--------------------------------------------------------------------------------------+
14110  |
14111  | $Source: docs/Articles/APIIntroductionMDL.h $
14112  |
14113  | $Copyright: (c) 2017 Bentley Systems, Incorporated. All rights reserved. $
14114  |
14115  +--------------------------------------------------------------------------------------*/
14116  namespace Bentley.ViewGroupHistory
14117  {
14118  using System;
14119  using Bentley.ECObjects;
14120  using Bentley.ECObjects.XML;
14121  using Bentley.ECObjects.Schema;
14122  using Bentley.ECObjects.Instance;
14123  using System.IO;
14124  using System.Xml;
14125  using Bentley.DgnPlatformNET;
14126  using System.Collections.Generic;
14127  using Bentley.MstnPlatformNET.Ribbon;
14128 
14129  /*====================================================================================**/
14132  /*==============+===============+===============+===============+===============+======*/
14133  public sealed class ViewGroupHistoryState
14134  {
14135  private static ViewGroupHistoryState s_state;
14136 
14137  // Name of Class to be added to the RibbonState schema. This must be unique across all RibbonComponent Providers
14138  private const string s_StateClassName = @"ViewGroupHistoryState";
14139 
14140  // Set up const strings for all the name of all ECProperties that will be needed to hold out state data
14141  private const string s_propname_AllDropDownWidth = @"AllDropDownWidth";
14142  private const string s_propname_AllDropDownHeight = @"AllDropDownHeight";
14143  private const string s_propname_PreviousDropDownWidth = @"PrevDropDownWidth";
14144  private const string s_propname_PreviousDropDownHeight = @"PrevDropDownHeight";
14145  private const string s_propname_NextDropDownWidth = @"NextDropDownWidth";
14146  private const string s_propname_NextDropDownHeight = @"NextDropDownHeight";
14147 
14149  // Private methods
14151  /*------------------------------------------------------------------------------------**/
14154  /*--------------+---------------+---------------+---------------+---------------+------*/
14155  private ViewGroupHistoryState ()
14156  {
14157  // Get the default RibbonState schema and define the class the will hold the state
14158  // values for the component this assemble provides.
14159  ECSchema schema = RibbonState.Schema;
14160  if (null != schema)
14161  LoadViewGroupHistoryStateClass (schema);
14162  }
14163 
14164  /*------------------------------------------------------------------------------------**/
14166  /*--------------+---------------+---------------+---------------+---------------+------*/
14167  private void RegisterProperty (IECClass stateClass, string name, IECPrimitiveType type)
14168  {
14169  stateClass.Add (new ECProperty (name, type));
14170  }
14171 
14172  /*------------------------------------------------------------------------------------**/
14175  /*--------------+---------------+---------------+---------------+---------------+------*/
14176  private void LoadViewGroupHistoryStateClass (ECSchema schema)
14177  {
14178  ECClass stateClass = new ECClass (s_StateClassName);
14179 
14180  RegisterProperty (stateClass, s_propname_AllDropDownWidth, ECObjects.DoubleType);
14181  RegisterProperty (stateClass, s_propname_AllDropDownHeight, ECObjects.DoubleType);
14182 
14183  RegisterProperty (stateClass, s_propname_PreviousDropDownWidth, ECObjects.DoubleType);
14184  RegisterProperty (stateClass, s_propname_PreviousDropDownHeight, ECObjects.DoubleType);
14185 
14186  RegisterProperty (stateClass, s_propname_NextDropDownWidth, ECObjects.DoubleType);
14187  RegisterProperty (stateClass, s_propname_NextDropDownHeight, ECObjects.DoubleType);
14188 
14189  schema.AddClass (stateClass);
14190  schema.TrimToSize ();
14191  }
14192 
14193  /*------------------------------------------------------------------------------------**/
14198  /*--------------+---------------+---------------+---------------+---------------+------*/
14199  private IECInstance StateInstance
14200  {
14201  get
14202  {
14203  return RibbonState.RibbonStateData.GetOrCreateInstanceByClassName (s_StateClassName);
14204  }
14205  }
14206 
14207  /*------------------------------------------------------------------------------------**/
14213  /*--------------+---------------+---------------+---------------+---------------+------*/
14214  private string GetPropertyAsString (string name, string defaultValue="")
14215  {
14216  return ECInstanceHelper.GetInstanceStringValue (StateInstance, name, defaultValue);
14217  }
14218 
14219  /*------------------------------------------------------------------------------------**/
14224  /*--------------+---------------+---------------+---------------+---------------+------*/
14225  private void SetPropertyString (string name, string value)
14226  {
14227  IECInstance instance = StateInstance;
14228  IECPropertyValue propVal = instance[name];
14229 
14230  if (propVal.IsNull || value != propVal.StringValue)
14231  {
14232  instance[name].StringValue = value;
14233  RibbonState.RibbonStateData.Dirty = true;
14234  }
14235  }
14236 
14237  /*------------------------------------------------------------------------------------**/
14243  /*--------------+---------------+---------------+---------------+---------------+------*/
14244  private double GetPropertyAsDouble(string name, double defaultValue=0.0)
14245  {
14246  return ECInstanceHelper.GetInstanceDoubleValue (StateInstance, name, defaultValue);
14247  }
14248 
14249  /*------------------------------------------------------------------------------------**/
14254  /*--------------+---------------+---------------+---------------+---------------+------*/
14255  private void SetPropertyDouble (string name, double value)
14256  {
14257  IECInstance instance = StateInstance;
14258  IECPropertyValue propVal = instance[name];
14259 
14260  if (propVal.IsNull || value != propVal.DoubleValue)
14261  {
14262  instance[name].DoubleValue = value;
14263  RibbonState.RibbonStateData.Dirty = true;
14264  }
14265  }
14266 
14267  /*------------------------------------------------------------------------------------**/
14273  /*--------------+---------------+---------------+---------------+---------------+------*/
14274  private double GetPropertyAsInt (string name, int defaultValue=0)
14275  {
14276  return ECInstanceHelper.GetInstanceIntValue (StateInstance, name, defaultValue);
14277  }
14278 
14279  /*------------------------------------------------------------------------------------**/
14284  /*--------------+---------------+---------------+---------------+---------------+------*/
14285  private void SetPropertyInt (string name, int value)
14286  {
14287  IECInstance instance = StateInstance;
14288  IECPropertyValue propVal = instance[name];
14289 
14290  if (propVal.IsNull || value != propVal.IntValue)
14291  {
14292  instance[name].IntValue = value;
14293  RibbonState.RibbonStateData.Dirty = true;
14294  }
14295  }
14296 
14297  /*------------------------------------------------------------------------------------**/
14303  /*--------------+---------------+---------------+---------------+---------------+------*/
14304  private bool GetPropertyAsBool (string name, bool defaultValue=false)
14305  {
14306  return ECInstanceHelper.GetInstanceBoolValue (StateInstance, name, defaultValue);
14307  }
14308 
14309  /*------------------------------------------------------------------------------------**/
14314  /*--------------+---------------+---------------+---------------+---------------+------*/
14315  private void SetPropertyBool (string name, bool value)
14316  {
14317  IECInstance instance = StateInstance;
14318  IECPropertyValue propVal = instance[name];
14319 
14320  if (propVal.IsNull || value != (bool)propVal.NativeValue)
14321  {
14322  instance[name].NativeValue = value;
14323  RibbonState.RibbonStateData.Dirty = true;
14324  }
14325  }
14326 
14328  // Public methods and properties
14330  /*------------------------------------------------------------------------------------**/
14333  /*--------------+---------------+---------------+---------------+---------------+------*/
14334  public static ViewGroupHistoryState StateData
14335  {
14336  get
14337  {
14338  if (null == s_state)
14339  s_state = new ViewGroupHistoryState ();
14340 
14341  return s_state;
14342  }
14343  }
14344 
14345  /*------------------------------------------------------------------------------------**/
14348  /*--------------+---------------+---------------+---------------+---------------+------*/
14349  public double AllDropDownWidth
14350  {
14351  get
14352  {
14353  return GetPropertyAsDouble (s_propname_AllDropDownWidth, 200);
14354  }
14355  set
14356  {
14357  SetPropertyDouble (s_propname_AllDropDownWidth, value);
14358  }
14359  }
14360 
14361  /*------------------------------------------------------------------------------------**/
14364  /*--------------+---------------+---------------+---------------+---------------+------*/
14365  public double AllDropDownHeight
14366  {
14367  get
14368  {
14369  return GetPropertyAsDouble (s_propname_AllDropDownHeight, 180);
14370  }
14371  set
14372  {
14373  SetPropertyDouble (s_propname_AllDropDownHeight, value);
14374  }
14375  }
14376 
14377  /*------------------------------------------------------------------------------------**/
14380  /*--------------+---------------+---------------+---------------+---------------+------*/
14381  public double PreviousDropDownWidth
14382  {
14383  get
14384  {
14385  return GetPropertyAsDouble (s_propname_PreviousDropDownWidth, 200);
14386  }
14387  set
14388  {
14389  SetPropertyDouble (s_propname_PreviousDropDownWidth, value);
14390  }
14391  }
14392 
14393  /*------------------------------------------------------------------------------------**/
14396  /*--------------+---------------+---------------+---------------+---------------+------*/
14397  public double PreviousDropDownHeight
14398  {
14399  get
14400  {
14401  return GetPropertyAsDouble (s_propname_PreviousDropDownHeight, 180);
14402  }
14403  set
14404  {
14405  SetPropertyDouble (s_propname_PreviousDropDownHeight, value);
14406  }
14407  }
14408 
14409  /*------------------------------------------------------------------------------------**/
14412  /*--------------+---------------+---------------+---------------+---------------+------*/
14413  public double NextDropDownWidth
14414  {
14415  get
14416  {
14417  return GetPropertyAsDouble (s_propname_NextDropDownWidth, 200);
14418  }
14419  set
14420  {
14421  SetPropertyDouble (s_propname_NextDropDownWidth, value);
14422  }
14423  }
14424 
14425  /*------------------------------------------------------------------------------------**/
14428  /*--------------+---------------+---------------+---------------+---------------+------*/
14429  public double NextDropDownHeight
14430  {
14431  get
14432  {
14433  return GetPropertyAsDouble (s_propname_NextDropDownHeight, 180);
14434  }
14435  set
14436  {
14437  SetPropertyDouble (s_propname_NextDropDownHeight, value);
14438  }
14439  }
14440 
14441  } // ViewGroupHistoryState
14442  } //namespace Bentley.ViewGroupHistory
14443 @endcode
14444 
14445 <H3>Example MstnRibbonState.xml file </H3>
14446 
14447 <P>Below is an example state xml file that contains data from two RibbonCoponent Providers. </P>
14448 
14449 @code{.unparsed}
14450 
14451  <?xml version="1.0" encoding="utf-8" standalone="yes"?>
14452  <!--Bentley MstnRibbonState Configuration File.-->
14453  <!--Modifying this file may render it invalid.-->
14454  <RibbonState>
14455  <RibbonViewState xmlns="RibbonState.01.00">
14456  <ActiveWorkFlowName>Drawing</ActiveWorkFlowName>
14457  <RibbonMinimizedState>False</RibbonMinimizedState>
14458  <LineStylePickerShowSearch>True</LineStylePickerShowSearch>
14459  <LineStylePickerShowRecentStyles>True</LineStylePickerShowRecentStyles>
14460  <LineStylePickerDisplayMode>All</LineStylePickerDisplayMode>
14461  <LineStylePickerDropDownWidth>180</LineStylePickerDropDownWidth>
14462  <LineStylePickerDropDownHeight>500</LineStylePickerDropDownHeight>
14463  </RibbonViewState>
14464  <ViewGroupHistoryState xmlns="RibbonState.01.00">
14465  <PrevDropDownWidth>200</PrevDropDownWidth>
14466  <PrevDropDownHeight>180</PrevDropDownHeight>
14467  </ViewGroupHistoryState>
14468  </RibbonState>
14469 
14470 @endcode
14471 
14472 
14473 
14474 
14475 
14476 
14477 
14478 
14479 
14480 
14481 
14482 
14483 
14484 
14485 
14486 *****************************************************************************************/
14487 
14488 
14489 /************************************************************************************//**
14490 * @addtogroup UpdateFiveDeprecatedFunctions
14491 *
14492 * <P>Below are listed a set of functions and methods deprecated in update 5, 10.05.00.xx builds </P>
14493 *
14494 <H3>Removed :</H3>
14495 
14496 @code{.unparsed}
14497 
14498  StatusInt Relationship::Moniker::FromAssocPoint (DgnModelRefP homeModel, DgnPlatform::AssocPoint const& ap);
14499 
14500 @endcode
14501 
14502 <H3>Replacement : </H3>
14503 
14504 
14505 @code{.unparsed}
14506 
14507  Moniker m (homeModel, ap);
14508 
14509 @endcode
14510 
14511 <H3>Removed :</H3>
14512 
14513 @code{.unparsed}
14514 
14515 StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elementIn, DgnModelRefP refModel);
14516 
14517 @endcode
14518 
14519 <H3>Replacement : </H3>
14520 
14521 
14522 @code{.unparsed}
14523 
14524  Moniker m (homeModel, PersistentElementPath (homeModel, elementIn));
14525 
14526 @endcode
14527 
14528 <H3>Removed :</H3>
14529 
14530 
14531 @code{.unparsed}
14532 
14533 StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elementIn, DgnPlatform::ElementId refAttid);
14534 
14535 @endcode
14536 
14537 <H3>Replacement : </H3>
14538 
14539 
14540 @code{.unparsed}
14541 
14542  Moniker m (homeModel, PersistentElementPath (refAttid, elementIn));
14543 
14544 @endcode
14545 
14546 <H3>Removed :</H3>
14547 
14548 
14549 @code{.unparsed}
14550 
14551 StatusInt Relationship::Moniker::FromNonLocalElement (DgnModelRefP homeModel, ElementRefP ref, DgnModelRefP refModel);
14552 
14553 @endcode
14554 
14555 <H3>Replacement : </H3>
14556 
14557 
14558 @code{.unparsed}
14559 
14560  Moniker m (homeModel, PersistentElementPath (refModel, ref));
14561 
14562 @endcode
14563 
14564 <H3>Removed :</H3>
14565 
14566 @code{.unparsed}
14567 
14568 StatusInt Relationship::Moniker::FromLocalElement (DgnModelRefP homeModel, DgnPlatform::ElementId elid);
14569 
14570 @endcode
14571 
14572  <H3> Replacement : </H3>
14573 
14574 
14575 @code{.unparsed}
14576 
14577  Moniker m (homeModel, PersistentElementPath (homeModel, elid));
14578 
14579 @endcode
14580 
14581 <H3>Removed :</H3>
14582 
14583 @code{.unparsed}
14584 
14585 StatusInt Relationship::Moniker::FromLocalElement (DgnModelRefP homeModel, ElementRefP ref);
14586 
14587 @endcode
14588 
14589  Use Instead :
14590 
14591 @code{.unparsed}
14592 
14593  Moniker m (homeModel, PersistentElementPath (homeModel, ref));
14594 
14595 @endcode
14596 
14597 <H3>Removed :</H3>
14598 
14599 @code{.unparsed}
14600 
14601 ElementRefP Relationship::Moniker::EvaluateElementRef ();
14602 
14603 @endcode
14604 
14605  Use Instead :
14606 
14607 
14608 @code{.unparsed}
14609 
14610  Moniker::EvaluateElement().GetElementRef();
14611 
14612 @endcode
14613 
14614 <H3>Removed :</H3>
14615 
14616 @code{.unparsed}
14617 
14618 ElementRefP Relationship::ParameterQuery::EvaluateElementRef();
14619 
14620 @endcode
14621 
14622 <H3>Replacement : </H3>
14623 
14624 @code{.unparsed}
14625 
14626  ParameterQuery::GetMoniker ().EvaluateElement().GetElementRef();
14627 
14628 @endcode
14629 
14630 <H3>Removed :</H3>
14631 
14632 @code{.unparsed}
14633 
14634 StatusInt DependencyManagerLinkage::AppendLinkageToMSElement (MSElementP el, DependencyLinkage const& dependencyData, size_t xtrabytes);
14635 
14636 @endcode
14637 
14638 <H3>Replacement : </H3>
14639 
14640 
14641 @code{.unparsed}
14642 
14643 EditElementHandle eeh (el);
14644 DependencyManagerLinkage::AppendLinkage (eeh, dependencyData, xtrabytes);
14645 
14646 @endcode
14647 
14648 <H3>Removed :</H3>
14649 
14650 @code{.unparsed}
14651 
14652 int DependencyManagerLinkage::DeleteLinkageFromMSElement (MSElementP element, UShort appID, UShort appValue);
14653 
14654 @endcode
14655 
14656 <H3>Replacement : </H3>
14657 
14658 @code{.unparsed}
14659 
14660 EditElementHandle eeh (el);
14661 DependencyManagerLinkage::DeleteLinkage (eeh, appID, appValue);
14662 
14663 @endcode
14664 
14665 <H3>Removed :</H3>
14666 
14667 @code{.unparsed}
14668 
14669 StatusInt DependencyManagerLinkage::GetLinkageFromMSElement (DependencyLinkageCP* ppDependencyLinkageInplace, MSElementCP element, UShort appID, UShort appValue);
14670 
14671 @endcode
14672 
14673 <H3>Replacement : </H3>
14674 
14675 @code{.unparsed}
14676 
14677 ElementHandle eeh (el);
14678 DependencyManagerLinkage::DeleteLinkage (ppDependencyLinkageInplace, eh, appID, appValue);
14679 
14680 @endcode
14681 
14682 <H3>Removed :</H3>
14683 
14684 @code{.unparsed}
14685 
14686 bool LxoSettings::IsSphericalCamera () const;
14687 
14688 @endcode
14689 
14690 <H3>Replacement : </H3>
14691 
14692 @code{.unparsed}
14693 
14694 CAMERAPROJECTION_Spherical == LxoSettings::GetCameraProjection ()
14695 
14696 @endcode
14697 
14698 <H3>Removed :</H3>
14699 
14700 @code{.unparsed}
14701 
14702 void LxoSettings::SetIsSphericalCamera (bool value);
14703 
14704 @endcode
14705 
14706 <H3>Replacement : </H3>
14707 
14708 
14709 @code{.unparsed}
14710 
14711 LxoSettings::SetCameraProjection (CAMERAPROJECTION_Spherical);
14712 
14713 @endcode
14714 
14715 <H3>Removed :</H3>
14716 
14717 @code{.unparsed}
14718 
14719 bool mdlAssoc_isTagged (DgnPlatform::ElementId * tagValue, MSElementCP elm);
14720 
14721 @endcode
14722 
14723 <H3>Replacement : </H3>
14724 
14725 @code{.unparsed}
14726 
14727 ElementId tagId = mdlElement_getID (&elm);
14728 
14729 @endcode
14730 
14731 
14732 <H3>Removed :</H3>
14733 
14734 @code{.unparsed}
14735 
14736 int mdlDependency_getDependents (DgnPlatform::ElementId *pDependents, DgnPlatform::ElementId rootElemId, DgnModelRefP rootModelRef, int maxDependents);
14737 
14738 @endcode
14739 
14740 <H3>Replacement : </H3>
14741 
14742 @code{.unparsed}
14743 
14744 int mdlDependency_getDependentElementRefs (ElementRefP *pDependents, DgnPlatform::ElementId rootElemId, DgnModelRefP rootModelRef, int maxDependents);
14745 pDependents[0].GetElementId () // if an element id of a dependent element is required
14746 
14747 @endcode
14748 
14749 <H3>Removed :</H3>
14750 
14751 @code{.unparsed}
14752 
14753 void DEllipse3d::Evaluate (DPoint3dR point, double theta) const;
14754 
14755 @endcode
14756 
14757 <H3>Replacement :</H3>
14758 
14759 @code{.unparsed}
14760 
14761 void DEllipse3d::RadiansToPoint (DPoint3dR point, double theta) const;
14762 
14763 @endcode
14764 
14765 <H3>Removed :</H3>
14766 
14767 @code{.unparsed}
14768 
14769 DPoint3d DPoint3d::FromXYZ (double x, double y, double z);
14770 
14771 @endcode
14772 
14773 <H3>Replacement :</H3>
14774 
14775 @code{.unparsed}
14776 
14777 DPoint3d DPoint3d::From (double x, double y, double z);
14778 
14779 @endcode
14780 
14781 <H3>Removed :</H3>
14782 
14783 @code{.unparsed}
14784 
14785 bool DoubleOps::SafeDivideDistance (double &result, double numerator, double denominator, double defaultResult = 0.0);
14786 
14787 @endcode
14788 
14789 <H3>Replacement :</H3>
14790 
14791 @code{.unparsed}
14792 
14793 ValidatedDouble DoubleOps::ValidatedDivideDistance(double a, double b, double defaultResult = 0.0);
14794 
14795 @endcode
14796 
14797 <H3>Removed :</H3>
14798 
14799 @code{.unparsed}
14800 
14801 PolyfaceHeaderR IPolyfaceConstruction::GetClientMeshR ();
14802 
14803 @endcode
14804 
14805 <H3>Replacement :</H3>
14806 
14807 @code{.unparsed}
14808 
14809 PolyfaceHeaderPtr IPolyfaceConstruction::GetClientMeshPtr ();
14810 
14811 @endcode
14812 
14813 <H3>Removed :</H3>
14814 
14815 @code{.unparsed}
14816 
14817 IPolyfaceConstructionPtr IPolyfaceConstruction::New (IFacetOptionsR options);
14818 
14819 @endcode
14820 
14821 <H3>Replacement :</H3>
14822 
14823 @code{.unparsed}
14824 
14825 IPolyfaceConstructionPtr IPolyfaceConstruction::Create (IFacetOptionsR options);
14826 
14827 @endcode
14828 
14829 <H3>Removed :</H3>
14830 
14831 @code{.unparsed}
14832 
14833 int MSBsplineCurve::NumberAllocatedKnots () const;
14834 
14835 @endcode
14836 
14837 <H3>Replacements :</H3>
14838 
14839 @code{.unparsed}
14840 
14841 size_t MSBsplineCurve::GetNumKnots () const;
14842 int MSBsplineCurve::GetIntNumKnots () const;
14843 
14844 @endcode
14845 
14846 <H3>Removed :</H3>
14847 
14848 @code{.unparsed}
14849 
14850 int MSBsplineCurve::NumberAllocatedPoles () const;
14851 
14852 @endcode
14853 
14854 <H3>Replacements :</H3>
14855 
14856 @code{.unparsed}
14857 
14858 size_t MSBsplineCurve::GetNumPoles () const;
14859 int MSBsplineCurve::GetIntNumPoles () const;
14860 
14861 @endcode
14862 
14863 <H3>Removed :</H3>
14864 
14865 @code{.unparsed}
14866 
14867 PolyfaceHeaderPtr PolyfaceHeader::New ();
14868 
14869 @endcode
14870 
14871 <H3>Replacement :</H3>
14872 
14873 @code{.unparsed}
14874 
14875 PolyfaceHeaderPtr PolyfaceHeader::CreateVariableSizeIndexed ();
14876 
14877 @endcode
14878 
14879 <H3>Removed :</H3>
14880 
14881 @code{.unparsed}
14882 
14883 PolyfaceCoordinateMapPtr PolyfaceCoordinateMap::New (PolyfaceHeaderR polyface);
14884 
14885 @endcode
14886 
14887 <H3>Replacement :</H3>
14888 
14889 @code{.unparsed}
14890 
14891 PolyfaceCoordinateMapPtr PolyfaceCoordinateMap::Create (PolyfaceHeaderR polyface);
14892 
14893 @endcode
14894 
14895 <H3>Removed :</H3>
14896 
14897 @code{.unparsed}
14898 
14899 void mdlRMatrix_rotatePoint (DPoint3dP pointP, RotMatrixCP matrixP);
14900 
14901 @endcode
14902 
14903 <H3>Replacement :</H3>
14904 
14905 @code{.unparsed}
14906 
14907 matrixP->Mutliply (*pointP);
14908 
14909 @endcode
14910 
14911 <H3>Removed :</H3>
14912 
14913 @code{.unparsed}
14914 
14915 void mdlRMatrix_unrotatePoint (DPoint3dP pointP, RotMatrixCP matrixP);
14916 
14917 @endcode
14918 
14919 <H3>Replacement :</H3>
14920 
14921 @code{.unparsed}
14922 
14923 void mdlRMatrix_multiplyTransposePoint (DPoint3dP pointP, RotMatrixCP matrixP);
14924 
14925 //or (better)
14926 
14927 matrixP->MutliplyTranspose (pointP);
14928 
14929 @endcode
14930 
14931 <H3>Removed :</H3>
14932 
14933 @code{.unparsed}
14934 
14935 void mdlRMatrix_unrotatePointArray (DPoint3dP pointArrayP, RotMatrixCP matrixP, int numPoints);
14936 
14937 @endcode
14938 
14939 <H3>Replacement :</H3>
14940 
14941 @code{.unparsed}
14942 
14943 matrixP->MultiplyTranspose (pointArrayP, pointArrayP, numPoints);
14944 
14945 @endcode
14946 
14947 <H3>Removed :</H3>
14948 
14949 @code{.unparsed}
14950 
14951 void mdlTMatrix_rotateScalePoint (DPoint3dP pointP, TransformCP transformP);
14952 
14953 @endcode
14954 
14955 <H3>Replacement :</H3>
14956 
14957 @code{.unparsed}
14958 
14959 transformP->MultiplyMatrixOnly (*pointP);
14960 
14961 @endcode
14962 
14963 <H3>Removed :</H3>
14964 
14965 @code{.unparsed}
14966 
14967 StatusInt mdlResource_loadFromStringList (WChar *pwString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum);
14968 
14969 @endcode
14970 
14971 <H3>Replacement :</H3>
14972 
14973 @code{.unparsed}
14974 
14975 StatusInt mdlResource_loadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc* m = NULL);
14976 StatusInt mdlResource_loadWString (WStringP, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum, MdlDesc* m = NULL);
14977 
14978 @endcode
14979 
14980 <H3>Removed :</H3>
14981 
14982 @code{.unparsed}
14983 
14984 StatusInt LoadFromStringList (WChar* pwString, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum);
14985 
14986 @endcode
14987 
14988 <H3>Replacement :</H3>
14989 
14990 @code{.unparsed}
14991 
14992 StatusInt mdlResource_loadWString (WStringR outString, RscFileHandle rfHandle, UInt32 listId, UInt32 stringNum, MdlDesc* m = NULL);
14993 StatusInt mdlResource_loadWString (WStringP, RscFileHandle rfHandle, UInt32 listId2, UInt32 stringNum, MdlDesc* m = NULL);
14994 
14995 @endcode
14996 
14997 <H3>Removed :</H3>
14998 
14999 @code{.unparsed}
15000 
15001 StatusInt mdlFilterIterator_setBaseFilter (FilterIteratorP pFilterIteratorIn, FilterID iBaseFilterIdIn);
15002 
15003 @endcode
15004 
15005 <H3>Replacement :</H3>
15006 Note: the parameter iBaseFilterIdIn from above was always ignored.
15007 
15008 @code{.unparsed}
15009 
15010 StatusInt mdlFilterIterator_reset (FilterIteratorP pFilterIteratorIn);
15011 
15012 @endcode
15013 
15014 <H3>Removed :</H3>
15015 
15016 @code{.unparsed}
15017 
15018 int mdlView_setLevels (bool onOffFlagIn, short* v7LevelMask, bool* viewList, bool doUpdate);
15019 
15020 @endcode
15021 
15022 <H3>Replacement :</H3>
15023 
15024 @code{.unparsed}
15025 
15026  int status = ERROR;
15027  BitMaskP pWorkingMask;
15028 
15029  mdlBitMask_create(&pWorkingMask, true);
15030  mdlBitMask_setFromBitArray (pWorkingMask, 64, reinterpret_cast<UShort *>(v7LevelMask));
15031 
15032  status = mdlView_changeLevelDisplayMaskMulti (MASTERFILE, viewList, pWorkingMask, onOffFlagIn ? LevelMaskOperation::On : LevelMaskOperation::Off, doUpdateIn);
15033 
15034  mdlBitMask_free(&pWorkingMask);
15035 
15036 @endcode
15037 
15038 <H3>Removed :</H3>
15039 
15040 @code{.unparsed}
15041 
15042 void mdlTag_registerSet (DgnModelRefP modelRef, MSElementCP el, DgnPlatform::ElementId uniqueId);
15043 
15044 @endcode
15045 
15046 <H3>Replacement :</H3>
15047 
15048 There is no replacement the tag is registered automatically when it is added to the file.
15049 
15050 <H3>Removed :</H3>
15051 
15052 @code{.unparsed}
15053 
15054 int mdlFile_createDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext);
15055 
15056 @endcode
15057 
15058 <H3>Replacement :</H3>
15059 
15060 @code{.unparsed}
15061 
15062 BeFileName fileName;
15063 
15064 mdlFile_create (&fileName, inname, envvar, iext);
15065 filename.c_str ();
15066 
15067 @endcode
15068 
15069 <H3>Removed :</H3>
15070 
15071 @code{.unparsed}
15072 
15073 int mdlFile_findDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext);
15074 
15075 @endcode
15076 
15077 <H3>Replacement :</H3>
15078 
15079 @code{.unparsed}
15080 
15081 BeFileName fileName;
15082 
15083 mdlFile_find (&fileName, inname, envvar, iext, FINDFILEOPTION_Default);
15084 filename.c_str ();
15085 
15086 @endcode
15087 
15088 <H3>Removed :</H3>
15089 
15090 @code{.unparsed}
15091 
15092 int mdlFile_findExtDeprecated (WCharP outname, WCharCP inname, WCharCP envvar, WCharCP iext, FINDFILE_Options options);
15093 
15094 @endcode
15095 
15096 <H3>Replacement :</H3>
15097 
15098 @code{.unparsed}
15099 
15100 BeFileName fileName;
15101 
15102 mdlFile_find (&fileName, inname, envvar, iext, options);
15103 filename.c_str ();
15104 
15105 @endcode
15106 
15107 
15108 <H3>Removed :</H3>
15109 
15110 @code{.unparsed}
15111 
15112 IPointCloudClassificationViewSettingsPtr IPointCloudClassificationViewSettings::GetPointCloudClassificationViewSettings(int viewIndex);
15113 
15114 @endcode
15115 
15116 <H3>Replacement :</H3>
15117 
15118 @code{.unparsed}
15119 
15120 IPointCloudClassificationViewSettingsPtr ptr = IPointCloudClassificationViewSettings::GetPointCloudClassificationViewSettings(viewIndex, ACTIVEMODEL);
15121 
15122 @endcode
15123 
15124 <H3>Removed :</H3>
15125 
15126 @code{.unparsed}
15127 
15128 bool IPointCloudClassificationViewSettings::GetClassificationState (UChar idx) const;
15129 
15130 @endcode
15131 
15132 <H3>Replacement :</H3>
15133 
15134 @code{.unparsed}
15135 
15136 bool IPointCloudClassificationViewSettings::GetState (UChar idx) const;
15137 
15138 @endcode
15139 
15140 <H3>Removed :</H3>
15141 
15142 @code{.unparsed}
15143 
15144 StatusInt mdlRaster_systemRasterContainerGet (DgnRasterVectorR collection);
15145 
15146 @endcode
15147 
15148 <H3>Replacement :</H3>
15149 
15150 @code{.unparsed}
15151 
15152 ModelRefIterator modelItr(pRootModel, iteratorType, depth);
15153 for (DgnModelRefP modelRefP = modelItr.GetFirst (); modelRefP; modelRefP = modelItr.GetNext ())
15154  {
15155  for each(DgnRasterP rasterP in DgnRasterCollection::GetRasters(modelRefP))
15156  {
15157  if(NULL != rasterP)
15158  //Do something;
15159  }
15160  }
15161 
15162 @endcode
15163 
15164 <H3>Removed :</H3>
15165 
15166 @code{.unparsed}
15167 
15168 int mdlVec_linePlaneIntersect (DPoint3dP intersectPt, DPoint3dCP linePt, DPoint3dCP lineNormal, DPoint3dCP planePt, DPoint3dCP planeNormal, int perpendicular);
15169 
15170 @endcode
15171 
15172 <H3>Replacement :</H3>
15173 
15174 @code{.unparsed}
15175 
15176 if (ERROR == mdlVec_linePlaneIntersect (intersectPt, linePt, lineNormal, planePt, planeNormal))
15177  // line is parallel to the plane.
15178 
15179 
15180 @endcode
15181 
15182 <H3>Removed :</H3>
15183 
15184 @code{.unparsed}
15185 
15186 DgnWorkSpacePtr DgnWorkSpace::Read (DgnDocumentMonikerCR cfgMoniker);
15187 
15188 @endcode
15189 
15190 <H3>Replacement :</H3>
15191 
15192 @code{.unparsed}
15193 
15194 DgnWorkSpacePtr DgnWorkSpace::Read(DgnDocumentMonikerCR cfgMoniker, DgnFolderMonikerCR configurationFolderRootPath);
15195 
15196 @endcode
15197 
15198 <H3>Removed :</H3>
15199 
15200 @code{.unparsed}
15201 
15202 DgnWorkSetPtr DgnWorkSet::Create(DgnWorkSpaceR workspace, WCharCP name, WCharCP descr);
15203 
15204 @endcode
15205 
15206 <H3>Replacement :</H3>
15207 
15208 @code{.unparsed}
15209 
15210 DgnWorkSetPtr DgnWorkSet::Create (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker, DgnDocumentMonikerCR dgnwsMoniker, WStringCR name, WCharCP descr);
15211 
15212 @endcode
15213 
15214 <H3>Removed :</H3>
15215 
15216 @code{.unparsed}
15217 
15218 DgnWorkSetPtr DgnWorkSet::Read (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker);
15219 
15220 @endcode
15221 
15222 <H3>Replacement :</H3>
15223 
15224 @code{.unparsed}
15225 
15226 DgnWorkSetPtr DgnWorkSet::Read (DgnWorkSpaceR workspace, DgnDocumentMonikerCR cfgMoniker, DgnDocumentMonikerCR DgnwsMoniker);
15227 
15228 @endcode
15229 
15230 <H3>Removed :</H3>
15231 
15232 @code{.unparsed}
15233 
15234 StatusInt mdlLevel_getParentId (DgnPlatform::LevelId* pParentLevelIdOut, DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);
15235 
15236 @endcode
15237 
15238 <H3>Replacement :</H3>
15239 
15240 None. Hierarchical levels are not supported anymore.
15241 
15242 <H3>Removed :</H3>
15243 
15244 @code{.unparsed}
15245 
15246 StatusInt mdlLevel_getChildCount (int* pChildLevelCountOut, DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);
15247 
15248 @endcode
15249 
15250 <H3>Replacement :</H3>
15251 
15252 None. Hierarchical levels are not supported anymore.
15253 
15254 <H3>Removed :</H3>
15255 
15256 @code{.unparsed}
15257 
15258 bool mdlLevel_isParent (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);
15259 
15260 @endcode
15261 
15262 <H3>Replacement :</H3>
15263 
15264 None. Hierarchical levels are not supported anymore.
15265 
15266 <H3>Removed :</H3>
15267 
15268 @code{.unparsed}
15269 
15270 bool mdlLevel_isChild (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);
15271 
15272 @endcode
15273 
15274 <H3>Replacement :</H3>
15275 
15276 None. Hierarchical levels are not supported anymore.
15277 
15278 <H3>Removed :</H3>
15279 
15280 @code{.unparsed}
15281 
15282 StatusInt mdlLevel_setParentId (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn, DgnPlatform::LevelId parentLevelIdIn);
15283 
15284 @endcode
15285 
15286 <H3>Replacement :</H3>
15287 
15288 None. Hierarchical levels are not supported anymore.
15289 
15290 <H3>Removed :</H3>
15291 
15292 @code{.unparsed}
15293 
15294 WCharCP mdlLevel_getPathName (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn);
15295 
15296 @endcode
15297 
15298 <H3>Replacement :</H3>
15299 
15300 None. Hierarchical levels are not supported anymore.
15301 
15302 <H3>Removed :</H3>
15303 
15304 @code{.unparsed}
15305 
15306 void SheetDef::GetWindowsPrinterName (WString& windowsPrinterName) const;
15307 void SheetDef::SetWindowsPrinterName (WChar const * windowsPrinterName);
15308 void SheetDef::GetPltFileName (WString& pltFileName) const;
15309 void SheetDef::SetPltFileName (WChar const * pltFileName);
15310 
15311 @endcode
15312 
15313 <H3>Replacement :</H3>
15314 
15315 The windows printer name and the plot file names are no longer stored on SheetDef. Their use has been deprecated.
15316 
15317 *****************************************************************************************/
15318 
#define MTASKID
Definition: dlogbox.r.h:337
#define ICONCMDID_OpenFile
Definition: dlogids.r.h:4994
DialogManager is a convenience class that provides methods to obtain information about the Microstati...
Definition: DialogManager.h:38
#define VBIT_CTRL
Definition: keys.r.h:277
Definition: UISyncManager.h:19
! Singleton that manages the list of IXCommands
Definition: XCommandManager.h:24
uint32_t UInt32
Definition: Bentley.r.h:128
#define NULL
Definition: Bentley.h:157
uint32_t RscType
Definition: ecimagekey.h:15
Definition: MicroStation.r.h:164
static XCommandManagerR GetManager()
Gets the singleton instance of the XCommandManager.
This section contains a conversion factor for the working units of the model.
UInt64 CommandNumber
Definition: DgnPlatformBaseType.r.h:76
struct IXCommand * IXCommandP
Definition: IXCommand.h:353
uint64_t UInt64
Definition: Bentley.r.h:131
#define XCMDLISTID_MstnPlatform
Definition: dlogids.r.h:1752
struct mdlDesc * MdlDescP
Definition: ConfigurationManager.h:13
IXCommandP FindXCommand(WCharCP commandId)
Finds an IXCommand in the list.
Command Resource for XCommands - Cross - platform / Cross UI Technology commands. ...
Definition: dlogbox.r.h:2756
#define NOACCEL
Definition: dlogbox.r.h:368
int32_t RscId
Definition: ecimagekey.h:16
#define DISCONNECT
DISCONNECT is a coordinate value that signifies a disconnected vertex in a string of points...
Definition: GeomApi.h:76
static void SendUISyncMessage(RscId syncGroupRscId, WStringR mdlTaskId, RscId syncItemId)
Send a message to UI items that need to refresh themselves when certain events occur.
char Utf8Char
Definition: Bentley.r.h:156
Command Item Button Resource supporting XCommands.
Definition: dlogbox.r.h:2804

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