oDlg:Activate( bLClicked, bMoved, bPainted, lCenter, bValid, lModal,;
                   bInit, bRClicked, bWhen )
-------------------------------------------------------------------------------


    ACTIVATE DIALOG <oDlg> ;
           [ VALID <uValid> ] ;
           [ WHEN <uWhen> ] ;
           [ ON [ LEFT ] CLICK <uClick> ] ;
           [ ON INIT <uInit> ] ;
           [ ON MOVE <uMoved> ] ;
           [ ON PAINT <uPaint> ] ;
           [ ON RIGHT CLICK <uRClicked> ] ;
           [ CENTER | CENTERED ] ;
           [ NOWAIT | NOMODAL ]



 PARAMETER:

  For a brief description of the standard ACTIVATE Parameter please open
  Related Topics:  and select  ACTIVATE WINDOW 


  <oDlg>       Is the reference to the Dialog Object that will be
               activated

  <uWhen>      will be performed before the dialog box starts, and permits
               the dialog to execute only if it returns a TRUE. This is like
               the WHEN clause in a GET

  <uInit>      This is perhaps the most interesting clause of our ACTIVATE .. 
               Command. The Actionblock will be executed after the dialog box 
               is created, but before it is shown on the screen. 
               In this situation the dialog box behaves like a Window, and we
               may do all kind of operations that we do to a window, like 
               placing a Message- or a Buttonbar on it.
               The Actionblock is definde as { |Self| <uValid> }, and 
               therefore gets the dialog object as the parameter Self.


  <uPaint>     Generally drawing action to be performed every Time that
               the dialog is repainted ( iE the dialog receives a WM_PAINT
               message from Windows). 

               bPainted is compiled to {|hDC, cPS| uPaint }.
               It receives two Parameters:
      
                      hDC    the Window Device Context Handle
                      cPS    Window PAINTSTRUCT as a String


  <CENTER>     This Keyword overrides the top and left coordinates of
               the dialog box and centers it on the screen when it is 
               painted. The width and height of the dialog box however 
               are NOT changed.

  <NOWAIT>     Determines that the dialog box is "modeless". A MODAL dialog, 
               which is most common, has to be ended before the user can 
               switch between the dialog and another window in the program. 
               If the dialog box is flagged as 'Sytem-modal' ( DS_SYSMODAL ),
               he can't even switch between the applikation and another 
               program before the dialog is explicitly closed !

               A modeless or nonModal dialog whereas means that other 
               dialog boxes may be working at the same time, behaving a bit 
               like an MDI Window. This is necessary for instance if you
               create a dialog with some kind of progress meter, or a
               search/replace dialog that stays opened for the next search/
               continue.

               NonModal programming requires some special care:

               * Take care of local variables: If you are using them then 
                 remember you will go out of the scope of the function 
                 where the modeless dialog box has been created, and this 
                 may cause problems if you forget this. 
                 Clipper works perfectly in these circumstances as it 
                 keeps 'live references' of the local variables inside of  
                 codeblocks, but only these will be 'alive' outside of the
                 function !

               * The same dialog box may be executed several times. Be 
                 aware of your DBF management, because in this circumstances 
                 your computer is like a NetWork, opening and accessing 
                 tables several times. 

               * FiveWin sets a limit of 20 simultaneous opened, nonModal
                 dialog boxes. This is done to preserve resources, as such
                 dialogs stresses windows more than common modal dialogs.



 DESCRIPTION:

  ACTIVATE DIALOG will actually show the dialog box on the screen. 
  Before a call to this method is made the dialog box is not yet visible. 
  Through the parameters that ACTIVATE receives special eventhandlers can
  be installed.

 EXAMPLE:

     +-------------------------------------------------------------+
     |  /* Center a Dialog on the Screen */                        |
     |  ACTIVATE DIALOG oDlg ;                                     |
     |   CENTERED                                                  |
     |                                                             |
     |  /* Move a resource dialog to a different Position */       |
     |  ACTIVATE DIALOG oDlg ;                                     |
     |   ON INIT oDlg:move( nTop, nRight )                         |
     |                                                             |
     |  /* Create a nonModal Dialog with a valid clause */         |
     |  ACTIVATE DIALOG oDlg ;                                     |
     |   NOWAIT ;                                                  |
     |   VALID( MsgInfo( "Testing valid in a Dialog"), .T. )       |
     |                                                             |
     +-------------------------------------------------------------+