oDlg := TDialog():New( nTop, nLeft, nBot, nRight, cTitle, cResName,;
                           hresources, lVbx, nStyle, nClrText, nClrBack,;
                           oBrush, oWnd, lPixel, oIcon, oFont, nHelpId )
-------------------------------------------------------------------------------


    DEFINE DIALOG <oDlg> ;
         [ NAME | RESNAME | RESOURCE <cResName> ] ;
         [ TITLE <cTitle> ] ;
         [ FROM <nTop>, <nLeft> TO <nBottom>, <nRight> ] ;
         [ LIBRARY | DLL <hResources> ] ;
         [ STYLE <nStyle> ] ;
         [ COLOR | COLORS <nClrFore> [,<nClrBack>] ];
         [ BRUSH <oBrush> ] ;
         [ WINDOW | DIALOG | OF <oWnd> ] ;
         [ ICON <oIco> ] ;
         [ FONT <oFont> ] ;
         [ HELP | HELPID <nHelpId> ]
         [ PIXEL ] ;
         [ VBX ] ;


 PARAMETER:


  <oDlg>       The Variable that will hold a reference to our Dialog Box 
               Object

  <cResName>   This String is the name of our dialog box in the resource
               ( either a .DLL or linked to the executable by RC.EXE ). You
               use the 'Rename' option from a resource editor to name the 
               dialog box.

  <cTitle>     The Title of the Dialog Box. You may also change the title 
               of a resource Dialog Box. With this you may use the same 
               Dialog Box for different purposes by just changing its Title

  <nTop>...    The coordinates of our Dialog box, we simulate text  
  <nRight>     coordinates. Internally Dialog boxes use neither text
               coordinates nor Pixels, they have a special unit based on
               the size of the selected Font.

  <hResources> By default this handle is the applications handle, when 
               using an .RC File, or the handle of the DLL when using 
               SET RESOURCES TO.... If you are using several DLLs at
               the same time, this Var should hold the Instance Handle of 
               the DLL containig the dialog box as a resource.


  <nStyle>     Specifies the dialog box styles. Please press
                Related Topics:  and select  Window styles  for
               detailed informations about the style flags.
               There are several samples in the SAMPLES\ subdirectory showing 
               you how to manipulate this value. If you are using a dialog 
               box from a resource then you have to select the style from 
               inside the resource editor.

  <nClrText>   The foreground color that is used to draw on the dialog box.
               This can either be a Windows COLOR number or a Clipper color 
               string (ie "R/G"), in which case the nClrBack parameter 
               will be ignored.

  <nClrBack>   The background color of the dialog box. This has to be a a
               MS-Windows COLOR number.

  <oBrush>     The brush object that paints the client area of the dialog 
               box. If this Parameter is skipped, then a default Brush ist 
               used.

  <oWnd>       The Parent Window object of this dialog box. If this Window
               is not specified then this dialog will be linked to the main 
               window of the application. This would result in that the the 
               controls of the dialog box paint their messages on the Message
               line of the Main Window.

  <oIcon>      An optional Icon Object that will be used when the dialog box 
               has been minimized. If none is provided, then the standard
               MS-Windows logo will be defaulted.

  <oFont>      The default font that will be used when a control or a text
               is painted to the dialog box without a defined Font.


  <nHelpId>    Is the Help Topic Identifier of our Dialog Box as a 
               numeric Constant

  <PIXEL>      Keyword that switches the translation of the coordinates
               unit from character based (default, a la Clipper) to pixels.
               If the dialog is created from resource, this parameter is
               not noticed.
                   
  <VBX>        Use this Keyword if you have one ore more VBX control in your
               dialog box, so that the necessary initialization is performed.



  DESCRIPTION:

   This Command creates a Dialog box


  HINTS:

   A lot of things to say about dialog boxes are directly related the
   attached controls, so its hard to say which belongs in the category
   DIALOGS and which would be better found in CONTROLS.
   We don't neeed redundance ( this guides are big enough anyway ), so
   here is my selection.

   First of all, what's the difference between Windows and Dialogs ?
   Dialog boxes are most often used for obtaining additional input from
   the user beyond what can be easily managed through a menu. They are in
   fact windows with additional functionality, and they inherite from the 
   TWINDOW() class.

   sizes:
   However, there is one big crux in dialogs, and that is why many languages 
   like Delphi or VB don't use them: They use a different unit of size 
   measurement than Windows. 

   While Windows are measured in pixels, dialog boxes use numbers based on 
   the size of an average system font character. Cols ( and width ) are 
   expressed in units of 1/4 of an average character width, while Rows
   ( and height ) are expressed in units of 1/8 of the  character height. 
   As a rule of thumb, you can assume that every dialog unit corresponds to 
   2 Pixels on a VGA Display ( Font Ratio 8 x 16 at 1/4 x 1/8 = 2 ).

   Why ? The original purpose was to have a size unit that will retain the 
   general dimensions and look of a dialog box regardless of the video 
   display's resolution. This as such is a honorable intension, but only
   Mr.Gates knows why the design became so complicated !

  
   Controls:
   What makes it even worse, is the fact that the dialog box behaves like
   a Window once it is created and activated. This means that you have to
   use pixel units again if you want to create a control for that dialog 
   after it has been instantiated. It also means that you can add features 
   of a window then which are normally not available in dialog boxes ;-} 

   Maybe you want a ButtonBar in a dialog box, so try this:

     +-------------------------------------------------------------+
     |  /* Button bar in a dialig box */                           |
     |   ACTIVATE DIALOG oDlg ;                                    |
     |    ON INIT CreateBar( oDlg )                                |
     |  [ more code ]                                              |
     |  RETURN                                                     |
     |                                                             |
     |  PROCEDURE CreateBar( oDlg )                                |
     |    LOCAL oBar                                               |
     |                                                             |
     |    DEFINE BUTTONBAR oBar SIZE 32,32 OF oDlg                 |
     |    DEFINE BUTTON RESOURCE "New" OF oBar ...                 |
     |    [ more Buttons .. ]                                      |
     |                                                             |
     |  RETURN oBar                                                |
     |                                                             |
     +-------------------------------------------------------------+


   resource:
   Dialog boxes are most often created with a resource editor. It is a good
   practice to set the font of your dialog box to MS Sans Serif/6 points. 
   Because this size is not available, Windows will use the 8 points size
   by default, which keeps your dialogs in the same size regardless of the 
   active system font and screen resolution. You should also be aware that
   some users will still be using 640x480 pixel mode, so make sure your
   dialog box fits within that size !


   Exit:
   Normally you will exit from a dialog with the oDlg:end() Message, 
   dispatched from one of your dialog controls. 
   When you (re)define the ID's for your controls you should be aware that 
   there are 2 default 'magic numbers', that you should avoid if you don't 
   want their behaviour: 
   it's simply IDOK ( defined as 1 ) and IDCANCEL ( which is a 2 ).

   If you press the ENTER Key ( which Clipper users often do <g> ), then
   Windows generates a WM_COMMAND Message with an IDOK as a Parameter , and 
   if you press the ESC Key, Windows will send this Message with IDCANCEL
   as a Parameter. 
   If this Message finds a receiver in any of your controls ( iE a control
   with the ID 1 or 2 ), it will exit the dialog, leaving the ID Code in
   the InstanceVar odlg:nResult. This is Ok for the ESC, but what about a
   user that presses ENTER instead of TAB in the first GET of your dialog ?

   To prevent this, start wasting numbers and don't use an ID of 1 or 2.

   On the other hand you can use this feature ( yeah, it's not a Bug ) to
   simplify keyboard handling :
   Assume you have a dialog which has 2 Pushbuttons defined, one OK ( ID 1 ) 
   and one CANCEL ( ID 2 ). Instead of writing an ACTION clause for both 
   you can do it the good old modal Clipper way and evaluate the return 
   Code in odlg:nResult _AFTER_ the ACTIVATE DIALOG ... clause :


     +-------------------------------------------------------------+
     |  /* Default Push Buttons. Note that it is not               |
     |     neccessary to redefine the Buttons ID 1/2 */            |
     |   DEFINE DIALOG oDlg RESOURCE "Project" OF oWnd             |
     |   REDEFINE GET cFile ID GET_NAME OF oDlg                    |
     |   ACTIVATE DIALOG                                           |
     |                                                             |
     |   IF oDlg:nResult == 1     // IDOK                          |
     |      [ ... do OK stuff .. ]                                 |
     |                                                             |
     |   ELSEIF oDlg:nResult == 2 // IDCANCEL                      |
     |      [ .. same here .. ]                                    |
     |   ENDIF                                                     |
     |  RETURN nil                                                 |
     |                                                             |
     +-------------------------------------------------------------+

   The 1/2 thing is just a convenient for C Programmers: on 1 they have
   a TRUE ( bit 0 = 1 ), and on 2 they have a FALSE ( yes, bit 0 = 0 ).
   I should mention here, that from FiveWin Version 1.9 on you have another
   possibility to define a Pusbutton as an Exitbutton: 
   the Option CANCEL. This Button will also exit an dialog without 
   additional coding, and it will skip any validation.