/**********************************************************************/
/**			  Microsoft LAN Manager 		     **/
/**		Copyright(c) Microsoft Corp., 1991		     **/
/**********************************************************************/

/*
    bltapp.txt
    CDD describing the APPLICATION class


    FILE HISTORY:
	rustanl     28-Jun-1991     Created

*/



The APPLICATION class is the base class for objects that
can be executed as applications.  It is the next generation
of the APPSTART class.	(APPSTART will stay around for a
while, because some test programs still use it.)

The APPLICATION constructor initializes necessary libraries
like BLT and Netlib.

The APPLICATOIN destructor terminates what the constructor
initialized.

The APPLICATION public Run method executes the application.
The most interesting task it performs is run the message loop.

APPLICATION inherits from BASE, and thus uses the BASE error
reporting scheme.  QueryError should be called, as usual,
immediately within every derived constructor.  It is
also called from within the Run method, much like it is
within DIALOG_WINDOW::Process.

Since we live in an object-oriented world, we'd like to
get rid of WinMain--that is, a function where the application
starts executing.  Instead, WinMain ought to be replaced be
an APPLICATION object which is then executed.  A programmer
must have the ability to indicate of which class an object
should be instantiated.  This is accomplished with the
SET_ROOT_OBJECT macro.	SET_ROOT_OBJECT takes a class name
as a parameter.  It sets up WinMain (hence, WinMain is conceptually
hidden from the programmer), instantiates the given class,
calls Run on the object to execute it, and then calls the destructor.

This means that all APPLICATION classes that can be passed
to SET_ROOT_OBJECT must take the same set of parameters.  These
are a subset of the parameters normally passed to WinMain, viz.
hInstance, pszCmdLine, and nShow.

APPLICATION currently does not have a virtual second stage
constructor like, for example, the LMOBJ, although such may
be added if deemed useful or necessary.

Here's a simple example of what is needed to do to write the
beginning of an application using APPLICATION:

    class MY_APPLICATION : public APPLICATION
    {
    public:
	MY_APPLICATION( HANDLE hInstance,
			CHAR * pszCmdLine,
			INT nShow );
	~MY_APPLICATION();

    };	// class MY_APPLICATION

    MY_APPLICATION::MY_APPLICATION( HANDLE hInstance,
				    CHAR * pszCmdLine,
				    INT nShow )
	:   APPLICATION( hInstance, pszCmdLine, nShow )
    {
	if ( QueryError() != NERR_Success )
	    return;

	//  Here you may, for example, create an application
	//  window.  If something goes awry, call ReportError
	//  and return.

    }  // MY_APPLICATION::MY_APPLICATION

    MY_APPLICATION::~MY_APPLICATION()
    {
	// nut'n much to do

    }  // MY_APPLICATION::~MY_APPLICATION


    //	The following line effectively replaces what used to
    //	be WinMain.  Conceptually, it indicates of which class
    //	an object should be instantiated and executed.

    SET_ROOT_OBJECT( MY_APPLICATION );

For a real example, see, e.g., the User Tool.
