Click above to get retro games delivered to your door ever month!

 1.2 The main window
--------------------------------------------------------------------------------

   Normally, to build your main window application you do as follows:

   #include "FiveWin.ch"

   static oWnd

   function Main()

      DEFINE WINDOW oWnd TITLE "My application"

      ACTIVATE WINDOW oWnd MAXIMIZED

   return nil

   In this sample you are selecting the most typical window, with default
   coordinates and style, and you start it at full open screen mode -MAXIMIZED-.
   If you want to place it at some position you may specify:

              ... FROM nTop, nLeft TO nBottom, nRight ...

              FROM 2, 2 TO 20, 60

   We simulate in these coordinates, text mode coordinates.

   ACTIVATE WINDOW will invoke automatically the main application event loop
   if it is not working yet. Internally, the application only need one
   event loop for all the windows.

   There are three main different ways to build your application window:

      * Defining a standard window (like the sample above).

      * Defining a MDI window: A multi document interface, this means
        a main window that will allow several child windows running
        inside it. For instance, Windows Program Manager is a MDI window.

      * Defining a DialogBox as the main application window: There are
        some situations where you don't need to implement a main window,
        with pulldown menu, buttonbar, etc... and you just need some
        operations to be done, and just a DialogBox should be the perfect
        way.

   FiveWin lets you start the application with all these above styles.

   In the sample above the style of the window as default is OVERLAPPED-
   WINDOW which means all the typical features you find in a window:
   caption, system menu, resizable border, min and max buttons.

   If you want to specify other styles, FiveWin offers you some clauses
   to select them:

   * NOSYSMENU
   * NOCAPTION
   * NOICONIZE
   * NOZOOM

   Also you may specify the combination of them you want, just doing:

          ... STYLE nOr( WS_BORDER, WS_MAXIMIZE, ... )

   These styles are defined inside INCLUDE\WINAPI.CH header file -which
   is automatically loaded by FiveWin.ch.-

   If you want to start a MDI -Multiple interface document- window, you
   just have to specify the clause MDI:

      DEFINE WINDOW oWnd TITLE "A MDI environment" MDI

      ACTIVATE WINDOW oWnd    // let's open it now in normal mode

      // You may also select ACTIVATE WINDOW oWnd ICONIZED
      // which will start the application as an icon.

   See the source code of IDE\SOURCE\IDE.prg if you want to see how to
   build and properly manage MDI environments. We also supply some
   samples in SAMPLES\TestMdi_.prg.

   MDI environments require some level of Windows expertise from the
   users of the application. If your customer is new to Windows, you
   may do better trying the standard main window way.

   FiveWin will automatically control all Windows messages that it
   receives. But, based on a xBase syntax, you may specify certain
   behaviors ON some events occurring.

             ACTIVATE WINDOW oWnd ;
                ON PAINT ... ;
                ON LEFT CLICK ... ;
                ON RESIZE ... ;

   See FiveWin.ch for a list of all the events we support. Normally this
   kind of control will not be necessary, but in some circumstances you
   may need it.

   Also, the main window of your application may include scrollbars. The
   typical Windows scrollbars on the edges of a window have to be built
   when defining the window:

      DEFINE WINDOW oWnd ... VSCROLL

      or

      DEFINE WINDOW oWnd ... HSCROLL

      or both of them

      DEFINE WINDOW oWnd ... VSCROLL HSCROLL

   If you select these styles, you may intercept the events they will
   generate through these clauses:

      ACTIVATE WINDOW oWnd ...
         ON UP ...
         ON DOWN ...
         ON LEFT ...
         ON RIGHT ...
         ON PAGEUP ...
         ON PAGEDOWN ...

   If you specify these styles, your window object oWnd will have defined
   two scrollbars objects:

         oWnd:oVScroll .and. oWnd:oHScroll

   So you may control and modify them directly -see scrollbars management-

   To end the execution of your main window -or any other window or
   DialogBox- you use the :End() method:

        oWnd:End()

   This tells the window object oWnd to finish working. If you specified
   a VALID clause when activating the window, the VALID clause will have
   to return .t. to allow ending the window. This is a typical situation:

       ACTIVATE WINDOW oWnd ;
          VALID MsgYesNo( "Do you want to end ?" )

   During your application, if you call oWnd:End(), or the user double
   click the window close button, or if the user decided to end Windows,
   the VALID will be executed and according to its result it will let or
   not end the window.

   Remember you may use oWnd:End() to end any kind of window or
   DialogBox: oDlg:End().

   There is no way to build the main window from resources, unless you
   start your application with a DialogBox:

   DEFINE DIALOG oDlg RESOURCE "Main"

   ACTIVATE DIALOG oDlg CENTERED

   In this situation, we are loading as a main application window the dialog
   box stored in resources as "main".

   Use a DialogBox as your main window only when you don't need a pulldown
   menu, neither a message bar or a buttonbar. Remember that normally a
   DialogBox will not maximize or iconize, so plan carefully what kind
   of window you may use as your main application window.

   Most of the time a normal window -as the first sample above- will be
   perfect.