GettingStartedMDL.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
*
* @endcode
*
*<H4>CONNECT Edition</H4> 
* @code{.unparsed}
* #include <Mstn\MdlApi\rsctext.r.h>

 #if defined (resource)
     @AspectRatio ASPECT_DEFINEACSBYELEMENT = 1.0; /* ICONCMDID_DefineACSByElement */
 #endif
*
* @endcode
*
*<H2>MSValueDescr in Hook Messages </H2>
*<P>The MSValueDescr struct has been introduced and is a C++ wrapper for the older ValueDescr struct introduced in V8. The MSValueDescr struct contains the data type and the value and also has methods that operate on that value. The struct is defined in <Mstn\MdlApi\MSValueDescr.h>. Any existing usages of ValueDescr, or any combination of a format type plus a ValueUnion, should be replaced with an MSValueDescr. Any functions that took a ValueDescr* should now take a MSValueDescrP.  </P>
*
*<P>The data types supported by MSValueDescr include: </P>
*<UL>
*       <LI>signed/unsigned 16, 32, 64 bit integers </LI>
        <LI>double </LI>
        <LI>WChar </LI>
        <LI>void* and data size </LI>
        <LI>Byte </LI>
        <LI>bool </LI>
*</UL>
*
*<P>MSValueDescr has multiple constructors which take specific data types. There are also copy methods and an = operator. There are numerous "Is", "Get", "Set" and "Compare" methods. Some of the "Get" methods will perform necessary numeric conversions, but will complain about signed/unsigned mismatches and possible data loss. </P>
*
* @note The FMT_STRING formatType and support for multi-byte values have been removed.
*
*<H3>MSValueDescr - Example Hook Message Change </H3>
*<P>Any instance of ValueDescr or a formatType/ValueUnion combination has been replaced by an MSValueDescrP in the dialog hook and dialog item hook message structs, which are defined in <Mstn\MdlApi\dlogitem.h>. As an example, here is the old DialogItemMessage.u.value followed by the new version. Note that the following variables in the 8.11 version have been replaced by a single MSValueDescrP in the CONNECT Edition: </P>
*<UL>
*       <LI>int formatType  </LI>
        <LI>ValueUnion value  </LI>
        <LI>char* stringValueP </LI>
        <LI>void* and data size </LI>
        <LI>int maxStringSize  </LI>
        <LI>int voidDataSize  </LI>
*</UL>
*
*<H4>8.11 </H4>
* @code{.unparsed}
*  struct          /* used by GETSTATE, SETSTATE, GETVALUE, SETVALUE */
    {
    BoolInt           hookHandled;     /* <= only for hooks,TRUE if handled */
    BoolInt           valueChanged;    /* <= on SET's if value changed */
    int               formatType;      /* defined in vartypes.h */
    ValueUnion        value;

    char*             stringValueP;    /* only if string */
    char*             formatStrP;      /* only if string */
    int               maxStringSize;   /* only if string & GETs */

    char*             accessStrP;      /* in case an item has more than one access string */
    int               voidDataSize;    /* if void pointer is being passed in ValueUnion */

    BoolInt           cancelled;       /* <= on SETSTATE, will prevent the following QUEUECOMMAND */
    } value;
*
* @endcode
*
*<H4>CONNECT Edition</H4>
* @code{.unparsed}
* /*----------------------------------------------------------------------+
  DITEM_MESSAGE_GETSTATE & DITEM_MESSAGE_SETSTATE
  DITEM_MESSAGE_GETVALUE & DITEM_MESSAGE_SETVALUE
  DITEM_MESSAGE_JOURNALSTATE
 +----------------------------------------------------------------------*/
 struct DialogItemValueArgs                                  
    {
    bool              hookHandled;     // <= for STATE messages, true if handled      
    MSValueDescrP     msValueDescrP;   // <> includes formatType, string, numeric & ptr values      
    CharP             accessStrP;      // => in case an item has more than one access string

    // GET messages
    WCharCP           formatStrP;      // => only if string

    // SET messages
    bool              valueChanged;    // <= on SET's if value changed
    bool              cancelled;       // <= on SETSTATE, prevent the following QUEUECOMMAND
    };
*
* @endcode
*
*<H3>MSValueDescr - Example Usages </H3>
*<P>Here are some example usages showing MSValueDescr "Get" and "Set" calls:  </P>
*
* @code{.unparsed}
* // GetLong
 long        iValue;
 iValue = dimP->u.value.msValueDescrP->GetLong();

 // SetLong
 long        index = 100;
 dimP->u.value.msValueDescrP->SetLong (index);

 // GetWString
 WString     wMyString;
 dimP->u.value.msValueDescrP->GetWString (wMyString);

 // GetWCharCP
 WCharCP     itemString = dimP->u.focusOut.msValueDescrP->GetWCharCP ();

 // GetWChar
 WChar        sBuffer[256] = {0};
 dimP->u.value.msValueDescrP->GetWChar (sBuffer, _countof(sBuffer));

 // SetWChar
 WString      wMyString(L"Hello World!");
 dimP->u.value.msValueDescrP->SetWChar (wMyString.c_str());
*
* @endcode
*
*<H2>What Is New? </H2>
*<P>A few "major" features have been added in the CONNECT Edition PowerPlatform and these are explained in dedicated sections below.  </P>
*
*<UL>
*       <LI>C++ APIs  </LI>
        <LI>C++ Hook Handlers  </LI>
        <LI>MDL Layout Manager </LI>
        <LI>WPF Support </LI>
        <LI>Telerik Controls - WPF & WinForms</LI>
*</UL>
*
*<P>Other features have also been added, including Double-Buffering, Color Schemes and New Dialog Items. </P>
*
*<H3>Double-Buffering for MDL Windows </H3>
*<P>Double-buffering has been added for MDL windows and dialogs, which greatly reduces any flickering, or "flishy-flashy", behavior. This feature is free - there is nothing extra you must do to turn this feature on. However, if you're doing some Generic dialog item drawing or GDI/GDI+ drawing into the window and there is still some flickering, an mdlWindow_doubleBuffer* API is available and is prototyped in <Mstn\MdlApi\mswindow.fdf>. There is also a GuiDoubleBufferRef helper class that wraps some of those C functions. </P>
*
*<H3>Color Schemes  </H3>
*<P>Some color schemes have been introduced that mimic the Office 2007 Silver, Blue and Black (Dark Gray) themes. This can be set via "Workspace menu > Preferences > Look and Feel". More color themes will be added and we will work on applying those themes across MDL, WinForms and WPF windows and controls.  </P>
*
*<H3>New Dialog Items / Controls </H3>
*<P>A couple of new dialog items have been added: </P>
*<UL>
*       <LI>CompactSlider control for Visualization team  </LI>
        <LI>FlowDocumentScrollViewer control for formatted text - wraps a WPF control </LI>
*</UL>
*
*<H3>C++ APIs </H3>
*<P>C++ APIs for the MSDialog, MSWindow and DialogItem structs and various dialog items have been introduced. These APIs will help those C++ developers who want a more object-oriented application and also those who are using Visual Studio IntelliSense. Adoption of the C++ APIs is optional and they may be introduced into your code gradually. The equivalent mdlWindow and mdlDialog API functions will remain in place, and those functions are listed below in the Method/Function tables. Not all of the dialog items have a C++ API, and we are evaluating the cost-benefit ratio to determine whether we should add more.  </P>
*
*<H3>MSDialog </H3>
*<P>The MSDialog struct is defined in <Mstn\MdlApi\MSDialog.h> and is a subclass of MSWindow. MSDialog is the new name for DialogBox and GuiDialog. The table below lists the MSDialog methods and the C-based mdlDialog functions they equate to.  </P>
*
*<H3>Static/Class Methods </H3>
*<table>
* <tr>
*   <th>MSDialog Method </th>
*   <th>Equivalent mdlDialog Function</th>
* </tr>
* <tr>
*       <td>Find</td>
*       <td>mdlDialog_findByTypeAndId</td>
* </tr>
* <tr>
*       <td>Open</td>
*       <td>mdlDialog_openWithMD</td>
* </tr>
* <tr>
*       <td>OpenMessageBox</td>
*       <td>mdlDialog_openMessageBox</td>
* </tr>
* <tr>
*       <td>OpenModal</td>
*       <td>mdlDialog_openModalWithMD</td>
* </tr>
* <tr>
*       <td>QueueCommandNumber</td>
*       <td>mdlDialog_cmdNumQueueExt</td>
* </tr>
* </table>
*
*<H3>MSDialog Methods </H3>
*<table>
 <tr><th>MSDialog Method</th>
        <th>Equivalent mdlDialog Function or Member</th>
        </tr>
<tr>
<td>AddHookHandler</td>
<td>mdlDialog_addHookHandler</td>
</tr>
<tr>
<td>Close</td>
<td>mdlDialog_close</td>
</tr>
<tr>
<td>CloseCommandQueue</td>
<td>mdlDialog_closeCommandQueue</td>
</tr>
<tr>
<td>FindItemAtPoint</td>
<td>mdlDialog_findItemIndex</td>
</tr>
<tr>
<td>GetCancelItem</td>
<td>mdlDialog_itemGetCancel</td>
</tr>
<tr>
<td>GetDefaultItem</td>
<td>mdlDialog_itemGetDefault</td>
</tr>
<tr>
<td>GetFontHeight</td>
<td>fontHeight member or mdlDialog_fontGetHeight</td>
</tr>
<tr>
<td>GetFontIndex</td>
<td>mdlDialog_fontIndexGet</td>
</tr>
<tr>
<td>GetFontInfo</td>
<td>mdlDialog_fontGetInfo</td>
</tr>
<tr>
<td>GetItemByIndex</td>
<td>mdlDialog_itemGetByIndex</td>
</tr>
<tr>
<td>GetItemByTypeAndId</td>
<td>mdlDialog_itemGetByTypeAndIdEx</td>
</tr>
<tr>
<td>GetItemPtrByTypeAndId</td>
<td>GetItemByTypeAndId method &amp; DialogItem.GetTypePtr</td>
</tr>
<tr>
<td>GetItemCount</td>
<td>mdlDialog_itemsGetNumberOf</td>
</tr>
<tr>
<td>GetLayoutHelper</td>
<td>mdlDialog_getLayoutHelper</td>
</tr>
<tr>
<td>GetOwnerMD</td>
<td>mdlDialog_ownerMDGet</td>
</tr>
<tr>
<td>GetResourceId</td>
<td>mdlDialog_getResourceId</td>
</tr>
<tr>
<td>GetRootRawItem</td>
<td>mdlDialog_rItemRootGet</td>
</tr>
<tr>
<td>GetStringWidth</td>
<td>mdlDialog_stringWidth</td>
</tr>
<tr>
<td>GetStringNWidth</td>
<td>mdlDialog_stringnWidth</td>
</tr>
<tr>
<td>GetUserData</td>
<td>mdlDialog_userDataPtrGet</td>
</tr>
<tr>
<td>HasFocus</td>
<td>mdlDialog_hasFocus</td>
</tr>
<tr>
<td>ItemSetEnabledByTypeAndId</td>
<td>mdlDialog_itemSetEnabledByTypeAndId</td>
</tr>
<tr>
<td>ItemSetValueByTypeAndId</td>
<td>mdlDialog_itemSetStringValueByTypeAndId</td>
</tr>
<tr>
<td>ItemSynchByTypeAndId</td>
<td>mdlDialog_itemSynchByTypeAndId</td>
</tr>
<tr>
<td>PopupClose</td>
<td>mdlDialog_popupClose</td>
</tr>
<tr>
<td>QueueCommandNumberByDb</td>
<td>mdlDialog_cmdNumQByDbExt</td>
</tr>
<tr>
<td>Refresh</td>
<td>mdlDialog_refresh</td>
</tr>
<tr>
<td>SendUserMessageToHook</td>
<td>mdlDialog_hookDialogSendUserMsg</td>
</tr>
<tr>
<td>SetCancelItem</td>
<td>mdlDialog_itemSetCancel</td>
</tr>
<tr>
<td>SetDefaultItem</td>
<td>mdlDialog_itemSetDefault</td>
</tr>
<tr>
<td>SetLayoutHelper</td>
<td>mdlDialog_setLayoutHelper</td>
</tr>
<tr>
<td>SetLastActionType</td>
<td>mdlDialog_lastActionTypeSet</td>
</tr>
<tr>
<td>SetUserData</td>
<td>mdlDialog_userDataPtrSet</td>
</tr>
<tr>
<td>Show</td>
<td>mdlDialog_show</td>
</tr>
</table>
*
*<H3>MSWindow </H3>
*<P>The MSWindow struct is defined in <Mstn\MdlApi\MSWindow.h> and is a subclass of BaseWindow. MSWindow is the new name for GuiWindow. The table below lists the MSWindow methods and the C-based mdlWindow functions they equate to. </P>
*<table>
<tr><th>MSWindow Method</th>
<th>mdlWindow Function or Member</th>
</tr>
<tr>
<td>Activate</td>
<td>mdlWindow_setInputFocusExt</td>
</tr>
<tr>
<td>ClearRect</td>
<td>mdlWindow_rectClear</td>
</tr>
<tr>
<td>Close</td>
<td>mdlWindow_close</td>
</tr>
<tr>
<td>GetAttributes</td>
<td>mdlWindow_attributesGet</td>
</tr>
<tr>
<td>GetContentRectGlobal</td>
<td>mdlWindow_contentRectGetGlobal</td>
</tr>
<tr>
<td>GetContentRectLocal</td>
<td>mdlWindow_contentRectGetLocal</td>
</tr>
<tr>
<td>GetGlobalRectGlobal</td>
<td>mdlWindow_globalRectGetGlobal</td>
</tr>
<tr>
<td>GetGlobalRectLocal</td>
<td>mdlWindow_globalRectGetLocal</td>
</tr>
<tr>
<td>GetViewport</td>
<td>m_viewPort member</td>
</tr>
<tr>
<td>GetDialogP</td>
<td>(MSDialogP) this if mdlWindow_isDialogBox</td>
</tr>
<tr>
<td>Hide</td>
<td>mdlWindow_hide</td>
</tr>
<tr>
<td>IsActive</td>
<td>mdlWindow_isActiveAndVisible</td>
</tr>
<tr>
<td>IsFocusable</td>
<td>attributes.isFocusable Member</td>
</tr>
<tr>
<td>IsObscured</td>
<td>guiWindow_isObscured</td>
</tr>
<tr>
<td>IsVisible</td>
<td>mdlWindow_isVisible</td>
</tr>
<tr>
<td>Show</td>
<td>mdlWindow_show</td>
</tr>
</table>
*
*<H3>BaseWindow </H3>
*<P>The BaseWindow struct is defined in <Mstn\MdlApi\BaseWindow.h> and is a subclass of WindowInfo.  </P>
*<table>
<tr>
<th>BaseWindow Method</th>
<th>mdlWindow Function or Member</th></tr>
<tr>
<td>GetDockExtent</td>
<td>dockExtent member</td>
</tr>
<tr>
<td>GetDockPosition</td>
<td>mdlWindow_getDocked</td>
</tr>
<tr>
<td>GetDockPriority</td>
<td>mdlWindow_getDockPriority</td>
</tr>
<tr>
<td>GetTitle</td>
<td>mdlWindow_titleGet</td>
</tr>
<tr>
<td>GetTitleCP</td>
<td>name member</td>
</tr>
<tr>
<td>IsDisplayed</td>
<td>mdlWindow_isDisplayed</td>
</tr>
<tr>
<td>Maximized</td>
<td>mdlWindow_isMaximized</td>
</tr>
<tr>
<td>Minimized</td>
<td>mdlWindow_isMinimized</td>
</tr>
<tr>
<td>SetTitle</td>
<td>mdlWindow_titleSet</td>
</tr>
</table>
*
*<H3>WindowInfo </H3>
*<P>The WindowInfo struct is also defined in <Mstn\MdlApi\BaseWindow.h>. </P>
* <table>
<tr>
<th>WindowInfo Method</th>
<th>mdlWindow Function or Member</th>
</tr>
<tr>
<td>GetNext</td>
<td>mdlWindow_getNext</td>
</tr>
<tr>
<td>GetPrevious</td>
<td>mdlWindow_getPrevious</td>
</tr>
<tr>
<td>GetGraphHandle</td>
<td>graphHandle member</td>
</tr>
<tr>
<td>GetScreenNumber</td>
<td>mdlWindow_screenNumGet</td>
</tr>
</table>
*
*<H3>DialogItem </H3>
*<P>The DialogItem struct is defined in <Mstn\MdlApi\DialogItem.h>. The table below lists the DialogItem methods and the C-based mdlDialog functions they equate to.  </P>
*<table>
<tr>
<th>DialogItem Method</th>
<th>mdlDialog Function or Member</th>
</tr>
<tr>
<td>Draw</td>
<td>mdlDialog_rItemDrawEx</td>
</tr>
<tr>
<td>GetAttributes</td>
<td>attributes member</td>
</tr>
<tr>
<td>GetColor</td>
<td>mdlDialog_rItemGetColor</td>
</tr>
<tr>
<td>GetDialog</td>
<td>rawItemP-&gt;ownerDialogP member</td>
</tr>
<tr>
<td>GetId</td>
<td>id member</td>
</tr>
<tr>
<td>GetLabel</td>
<td>mdlDialog_rItemLabelGet</td>
</tr>
<tr>
<td>GetLabelLength (# characters)</td>
<td>mdlDialog_rItemLabelLengthGet</td>
</tr>
<tr>
<td>GetLabelWidth (# pixels)</td>
<td>GetLabelWidth</td>
</tr>
<tr>
<td>GetNextVisible</td>
<td>mdlDialog_itemGetNextVisible</td>
</tr>
<tr>
<td>GetOwnerItem</td>
<td>mdlDialog_rItemOwnerItemGet</td>
</tr>
<tr>
<td>GetPopupMenuText</td>
<td>mdlDialog_rItemPopupMenuLabelGet</td>
</tr>
<tr>
<td>GetRawItem</td>
<td>rawIPtemP member</td>
</tr>
<tr>
<td>GetRect</td>
<td>rect member</td>
</tr>
<tr>
<td>GetType</td>
<td>type member</td>
</tr>
<tr>
<td>GetState</td>
<td>mdlDialog_rItemStateGet</td>
</tr>
<tr>
<td>GetTypePtr</td>
<td>static_cast&lt;T&gt; if (itemType == this-&gt;type)</td>
</tr>
<tr>
<td>GetValue (MSValueDescrR)</td>
<td>mdlDialog_rItemValueGet</td>
</tr>
<tr>
<td>GetValue (WStringR)</td>
<td>mdlDialog_rItemStringValueGet</td>
</tr>
<tr>
<td>HasFocus</td>
<td>attributes.hasFocus member</td>
</tr>
<tr>
<td>Hide</td>
<td>mdlDialog_rItemHide</td>
</tr>
<tr>
<td>IsEnabled</td>
<td>attributes.enabled member</td>
</tr>
<tr>
<td>IsFocusable</td>
<td>mdlDialog_rItemIsFocusable</td>
</tr>
<tr>
<td>IsDisplayable</td>
<td>mdlDialog_rItemIsDisplayable</td>
</tr>
<tr>
<td>Move</td>
<td>mdlDialog_rItemMove</td>
</tr>
<tr>
<td>Obscure</td>
<td>mdlDialog_rItemObscure (true)</td>
</tr>
<tr>
<td>PopupClose</td>
<td>mdlDialog_rItemPopupClose</td>
</tr>
<tr>
<td>PopupOpen</td>
<td>mdlDialog_rItemPopupOpen</td>
</tr>
<tr>
<td>ReloadData</td>
<td>mdlDialog_rItemReloadData</td>
</tr>
<tr>
<td>SetBalloonText</td>
<td>mdlDialog_rItemBalloonTextSet</td>
</tr>
<tr>
<td>SetColor</td>
<td>mdlDialog_rItemSetColor</td>
</tr>
<tr>
<td>SetDisabledBalloonText</td>
<td>mdlDialog_rItemDisabledBalloonTextSet</td>
</tr>
<tr>
<td>SetEnabled</td>
<td>mdlDialog_rItemEnabledStateSet</td>
</tr>
<tr>
<td>SetExtent</td>
<td>mdlDialog_rItemExtentSet</td>
</tr>
<tr>
<td>SetFlyoverText</td>
<td>mdlDialog_rItemFlyoverTextSet</td>
</tr>
<tr>
<td>SetLabel</td>
<td>mdlDialog_rItemLabelSet</td>
</tr>
<tr>
<td>SetLabelFont</td>
<td>mdlDialog_rItemLabelFontSet</td>
</tr>
<tr>
<td>SetPopupMenuText</td>
<td>mdlDialog_rItemPopupMenuTextSet</td>
</tr>
<tr>
<td>SetState</td>
<td>mdlDialog_rItemStateSet</td>
</tr>
<tr>
<td>SetValue (MSValueDescrCR)</td>
<td>mdlDialog_rItemValueSet</td>
</tr>
<tr>
<td>SetValue (WCharCP)</td>
<td>mdlDialog_rItemStringValueSet</td>
</tr>
<tr>
<td>Show</td>
<td>mdlDialog_rItemShow</td>
</tr>
<tr>
<td>Synchronize</td>
<td>mdlDialog_rItemSynch</td>
</tr>
<tr>
<td>SynchornizeOthers</td>
<td>mdlDialog_rItemSynchOthers</td>
</tr>
<tr>
<td>Unobscure</td>
<td>mdlDialog_rItemObscure (false)</td>
</tr>
</table>
*
*<H3>Dialog Items </H3>
*<P>Some of the MDL Dialog Items have been exposed as new structs with methods. The <Mstn\MdlApi\DialogItems.h> header includes a header per Dialog Item that has an associated struct. As mentioned before, we are evaluating the cost-benefit ratio to determine whether we should add more. So other items will be added on an as-needed basis.  </P>
*<UL>
*       <LI>Container.h</LI>
*       <LI>ContainerPanel.h </LI>
*       <LI>ListBox.h </LI>
*       <LI>OptionButton.h </LI>
*       <LI>PushButton.h </LI>
*       <LI>TextBox.h</LI>*
*</UL>
*
*<H2>C++ Hook Handlers </H2>
*<P>The ability to develop Dialog Hooks and Dialog Item Hooks in C++ has been added. The C++ version of a hook is known as a "Hook Handler". There is a base class for the hook handlers: DialogHookHandler and DialogItemHookHandler. These are defined in <Mstn\MdlApi\dlogitem.h>. There are virtual methods for each of the hook message types, and there is a structure for most of the message types. The same structures from the DialogMessage and DialogItemMessage "u" unions are used as arguments to the hook handler methods. This introduces a level of type safety that did not exist with the "u" unions. The only limitation to this new architecture is that switch case "fall-through" is no longer possible. However, this limitation can easily be compensated for with a private method that one or more hook handler methods call. </P>
*
*<H3>Example of Message Type Structs from dlogitem.h </H3>
*<P>The Message Type struct examples below are in <Mstn\MdlApi\dlogitem.h>. The structs that were defined directly in the DialogMessage and DialogItemMessage "u" unions in V8i were split out into separate structs in CONNECT Edition, as you see below. Those structs are then referenced in DialogMessage, DialogItemMessage and the various hook handler methods.  </P>
*
* @code{.unparsed}
*/*-----------------------------------------------------------------------
  DIALOG_MESSAGE_CREATE
  Sent before item hooks are sent create messages
 +-----------------------------------------------------------------------*/
 struct DialogCreateArgs
    {
    bool                            createFailed;           /* <= set true if error */
    DialogHookInterests             interests;              /* <= */
    void**                          userDataPP;             /* <= */
    DialogBoxRsc*                   dialogBoxRP;            /* => */
    };

 typedef struct DialogCreateArgs&   DialogCreateArgsR;

 /*-----------------------------------------------------------------------
  DIALOG_MESSAGE_INIT
  sent after all item hooks are sent create messages
 +-----------------------------------------------------------------------*/
 struct DialogInitArgs
    {
    bool                            initFailed;             /* <= set true if error */
    };

 typedef struct DialogInitArgs&   DialogInitArgsR;
*
*
* @endcode
*
*<H3>DialogMessage struct excerpt from dlogitem.h </H3>
*
* @code{.unparsed}
* struct DialogMessage
    {
    bool                            msgUnderstood;          /* <= message understood? */
    DialogMessageType               messageType;            /* => message type */
    MSDialogP                       db;                     /* => dialog box handle */
    long                            dialogId;               /* => resource id of dialog box */
    void*                           userDataP;              /* => set by user during CREATE */
    union
        {                                                   
        DialogHookResolveArgs       hookResolve;            /* DIALOG_MESSAGE_HOOKRESOLVE */

        DialogCreateArgs            create;                 /* DIALOG_MESSAGE_CREATE */
        DialogInitArgs              init;                   /* DIALOG_MESSAGE_INIT */

        . . .

        } u;
    };

* @endcode
*
*<H3>DialogHookHandler struct excerpt from dlogitem.h </H3>
*
* @code{.unparsed}
*struct DialogHookHandler
    {
    MSDialogP   m_dbP;
    void*       m_userDataP;

    DialogHookHandler (MSDialogP dbP) : m_dbP (dbP) {}
    virtual ~DialogHookHandler() {}

    MSDialogP    GetDbP() { return m_dbP; }

    void         SetUserDataP (void *v) { m_userDataP = v; }
    void*        GetUserDataP () { return m_userDataP; }

    virtual bool OnCreate       (DialogCreateArgsR      create)         { return false; }
    virtual bool OnInit         (DialogInitArgsR        init)           { return false; }

    . . .

    };
*
* @endcode
*
*<H3>Example Dialog Hook Handler in Application Code </H3>
*<P>Each dialog hook handler is a subclass of DialogHookHandler. Hook IDs are still supported and can be referenced in a resource file. A static method within the hook handler serves as the function published as the dialog hook. As a convention, this method should be named "HookResolve". When a dialog is being created and the dialog hook ID to function association is being resolved, the Dialog Manager sends a DIALOG_MESSAGE_HOOKRESOLVE message to the dialog hook. The "HookResolve" method is responsible for instantiating the dialog hook handler instance, setting the dmP->u.hookResolve.hookHandlerP member to that handler object, and setting dmP->msgUnderstood to true. Thereafter, virtual method overrides on the dialog hook handler object will be called for each message.  </P>
*
* @code{.unparsed}
* // Dialog Hook Handler
 struct MyDialogHookHandler : DialogHookHandler
    {
    static void HookResolve (DialogMessage *dmP)
        {
        if (DIALOG_MESSAGE_HOOKRESOLVE == dmP->messageType)
            {
            dmP->u.hookResolve.hookHandlerP = new MyDialogHookHandler (dmP->db);
            dmP->msgUnderstood = true;
            }
        }

    // Item Hook Handler Constructor
    MyDialogHookHandler (MSDialogP dbP) : DialogHookHandler (dbP) {}

    // Dialog Hook Handler Method override
    virtual bool OnCreate (DialogCreateArgsR create) override
        {
        // OnCreate processing
        return true;
        }

    // Other hook handler method overrides . . .
    };
*
* @endcode
*
*<H3>Example Dialog Item Hook Handler application code </H3>
*<P>Similar to the DialogHookHandler, each dialog item hook handler is a subclass of DialogItemHookHandler. The item hook IDs are still supported and can be referenced in a resource file. A static method within the item hook handler serves as the function published as the item hook. As a convention, this method should be named "HookResolve". When a dialog item is being created and the item hook ID to function association is being resolved, the Dialog Manager sends a DITEM_MESSAGE_HOOKRESOLVE message to the item hook. The "HookResolve" method is responsible for instantiating the item hook handler instance, setting the dimP->u.hookResolve.hookHandlerP member to that handler object, and setting dimP->msgUnderstood to true. Thereafter, virtual method overrides on the item hook handler object will be called for each message. </P>
*
* @code{.unparsed}
*// Dialog Item Hook Handler 
 struct MyItemHookHandler : DialogItemHookHandler
    {
    // Dialog Hook replacement function
    static void HookResolve (DialogItemMessage *dimP)
        {
        if (DITEM_MESSAGE_HOOKRESOLVE == dimP->messageType)
            {
            dimP->u.hookResolve.hookHandlerP = new MyItemHookHandler (dimP->db, dimP->dialogItemP);
            dimP->msgUnderstood = true;
            }
        }

    // Item Hook Handler Constructor
    MyItemHookHandler (MSDialogP dbP, DialogItemP diP) : DialogItemHookHandler (dbP, diP) {}

    // Item Hook Handler Method override
    virtual bool OnCreate (DialogItemCreateArgsR create) override
        {
        // OnCreate processing 
        return true;
        }

    // Other hook handler method overrides . . .
    };
*
* @endcode
*
*<H3>Example DialogHookInfo hook array in application code </H3>
*<P>Dialog hook IDs and item hook IDs are still supported and can be referenced in a resource file. A hook function per ID is still required and is still published by calling mdlDialog_hookPublish. But when using dialog and/or item hook handlers, that function is usually simply a static method in the hook handler, and by convention is named "HookResolve". The example below shows the ID to HookResolve static method association. </P>
*
*@code{.unparsed}
*static DialogHookInfo  uHooks[] =
     {
     {HOOKDIALOGID_MyDialog,         (PFDialogHook) MyDialogHookHandler::HookResolve},
     {HOOKITEMID_MyItem,             (PFDialogHook) MyItemHookHandler::HookResolve},
     . . .
     };

 . . .

 /* Publish the dialog item hooks */
 mdlDialog_hookPublish (_countof(uHooks), uHooks);
*
* @endcode
*
*<H2>MDL Layout Manager</H2>
*<P>In an MDL Dialog Box item list specification, you can only specify a static X and Y position and a width and height for a dialog item. In code, you can alter those positions and sizes, especially when the dialog is being resized. But implementing a resizable dialog can be tedious. In addition, adjusting aspect ratios by localization teams is rather expensive. As stated before, we will not be converting all MDL dialogs to WPF in the CONNECT Edition release.  </P>
*
*<P>A dialog layout system provides a simple and powerful way of automatically arranging child controls within a dialog to ensure that they make good use of the available space. For the CONNECT Edition release, we have added a layout system to the MDL Dialog Manager. We implemented an independent layout engine library and integrated it into the MDL Dialog Manager via a C++ API. We have also added the ability to specify layout parameters in a dialog resource. The inspiration for our Layout Manager came from the layout systems in Qt, WPF and Java. Those layout systems are used to describe how controls are laid out in an application's user interface. They automatically position and resize controls 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. Different label widths are automatically accommodated. Since the layout engine is independent, we can also use it in MFC dialogs.  </P>
*
*<H3>Layout Types </H3>
*<P>There are 5 different layout types in the Layout Manager. </P>
*<UL>
*       <LI>GridLayout - lays out controls in rows and columns </LI>
*       <LI>StackLayout - lines up controls horizontally or vertically </LI>
*       <LI>DockLayout - put controls along the top, bottom, left or right  </LI>
*       <LI>FlowLayout - lines up controls horizontally as space permits then puts them on a separate line below when there's not enough space  </LI>
*       <LI>SplitterLayout - put controls on either size of a Sash, or Splitter, control </LI>
*</UL>
*
*<H3>Dialog Manager Integration </H3>
*<P>The independent layout engine library source is located in the UIFramework repository. The layout engine is integrated into the MDL Dialog Manager via a set of C++ classes that are defined in <Mstn\MdlApi\GuiLayout.h>.  </P>
*<UL>
*       <LI>GuiLayoutHelper - contains the overall layout for a dialog  </LI>
*       <LI>GuiLayoutControl - layout wrapper for a dialog item in the dialog </LI>
*       <LI>GuiLayoutLabel - layout wrapper for a label in the dialog </LI>
*       <LI>GuiLayoutContainerPanel - layout wrapper for a ContainerPanel in the dialog  </LI>
*       <LI>GuiSplitterHandle - used to easily layout a control on either side of a Sash control  </LI>
*       <LI>GuiLayoutProperties - contains layout-oriented properties for dialog items and layouts  </LI>
*</UL>
*
*<P>The GuiLayoutHelper maintains the top-level layout for the dialog. GuiLayoutControls are used as wrappers for each of the dialog items on the dialog. When an item is added to a layout using the GuiLayoutControl class, the caller specifies size policies and optional margins and spacing. A size can be specified as fixed or a minimum, maximum and preferred size can be specified via method overrides. The RawItemHdr for each dialog item has a 'layoutPropertiesP' member which points to a GuiLayoutProperties struct. Layout properties such as Size Policy, Margins and Minimum Size are located in this struct. Numerous layouts can be nested to achieve the overall layout for the dialog.  </P>
*
*<H3>More Information </H3>
*<P>More information on the MDL Dialog Layout Manager can be found on the following pages:  </P>
*<UL>
*       <LI>@DialogBoxLayoutManager "Layout Manager For Dialog Box" </LI>
*       <LI>@LayoutManagerMigration "Layout Manager Migration Guide" </LI>
*</UL>
*
*<H2>WPF </H2>
*<P>Windows Presentation Foundation, or WPF, is the newest Windows desktop UI framework offered by Microsoft. It was introduced in .NET 3.0 in late 2006. At the request of the Visual Studio 2010 team, some major performance and visual improvements were introduced in .NET 4.0 in 2010. The development languages used are XAML (eXtensible Application Markup Language), which is an XML-based declarative language used to specify the UI elements and layout, and either C# or VB.NET. WPF renders using DirectX instead of GDI/GDI+, and it aims to unify a number of common user interface elements, such as 2D/3D rendering, fixed and adaptive documents, typography, vector graphics, animation and media.  </P>
*<P>Two of WPF's main strengths are:  </P>
*<OL>
*       <LI>the separation between the look of the UI, based on styles and templates, and the processing for the UI, based on commands and events </LI>
*       <LI> data binding, which establishes a relationship that tells WPF to extract some information from a source object and use it to set a property in a target object.The target object is always a WPF dependency property, and it's usually in a WPF element derived from DependencyProperty .The source can be properties of another WPF Element or Control, properties in any CLR object, XML fragments or ADO.NET data object.Many features within WPF rely heavily on the data binding system.  </LI>
*</OL>
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
















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