Initializing_the_application

Initializing an ObjectWindows application takes four steps:

• Constructing the application object
• Initializing the application
• Initializing each new instance
• Initializing the main window

Constructing the application object

When you construct a TApplication object, it calls its TApplication::InitApplication(), TApplication::InitInstance(), and TApplication::InitMainWindow() member functions to start the application. You can override any of those members to customize how your application initializes. You must override InitMainWindow to have a useful application. To override a function in TApplication you need to derive your own application class from TApplication.

The constructor for the TApplication-derived class TMyApplication, shown in the examples that follow, takes the application name as its only argument; its default value is zero, for no name. The application name is used for the default main window title and in error messages. The application name is referenced by a char far* member of the TModule base class called Name. You can set the application name one of two ways:

• Your application class constructor can explicitly call TApplication's constructor, passing the application name onto TApplication. The following example shows this method:

  #include <owl/applicat.h>
  class TMyApplication: public owl::TApplication
  {
  public:
  // This constructor initializes the base class constructor
  TMyApplication(const owl::tstring name = owl::tstring()) : owl::TApplication(name) {}
  .
  .
  .
  };

• Override one of TApplication's initialization functions, usually InitMainWindow, and set the application name there. The following example shows this method:

  #include <owl/applicat.h>
  class TMyApplication: public owl::TApplication
  {
  public:
  // This constructor just uses the default base class constructor.
  TMyApplication(const owl::tstring name = owl::tstring()) : Name(name) {}
  void InitMainWindow()
  {
  SetName(Name);
  }
  .
  .
  .
  protected:
  owl::tstring Name;
  };

ObjectWindows applications do not require an explicit WinMain function; the ObjectWindows libraries provide one that performs error handling and exception handling. You can perform any initialization you want in the OwlMain function, which is called by the default WinMain function.

To construct an application object, create an instance of your application class in the OwlMain function. The following example shows a simple application object's definition and instantiation:

 #include <owl\applicat.h>

 class TMyApplication: public TApplication
 {
 public:
   TMyApplication(const owl::tstring name): TApplication(name) {}
  };

 int OwlMain(int argc, char* argv[])
 {
   return TMyApplication("Wow!").Run();
 }

Initializing the application

TApplication contains three initialization functions:

• TApplication::InitApplication() Initializes the first instance of the application.
• TApplication::InitInstance() Initializes each instance of the application.
• TApplication::InitMainWindow() Initializes the application's main window.

How these functions are called depends on whether or not this is the first instance of the application. For 16-bit applications, InitApplication is called only for the first instance of the application on the system. InitInstance is the next function called for the first instance, and it is the first function called by additional instances. InitInstance calls InitMainWindow.

In the case of 32-bit applications, each application runs in its own address space, with no shared instance data, making each instance a first instance. Every time you start a 32-bit application, it performs both first-instance initialization and each-instance initialization.

If the current instance is a first instance (indicated by the data member hPrevInstance being set to zero), InitApplication is called. You can override InitApplication in your derived application class; the default InitApplication has no functionality.

For example, you could use first-instance initialization to make the main window's caption indicate whether it's the first instance. To do this, add a data member called WindowTitle in your derived application class. In the constructor, set WindowTitle to "Additional Instance". Then override InitApplication to set WindowTitle to "First Instance". If your application is the first instance of the application, InitApplication is called and overwrites what the constructor set WindowTitle to. The following example shows how the code might look:

 #include <owl\applicat.h>
 #include <owl\framewin.h>
 using namespace owl;

 class TTestApp : public TApplication
 {
   public:
    TTestApp() : 
      TApplication("Instance Tester"),
      WindowTitle("Additional Instance") {}

 protected:
  tstring WindowTitle;

  void InitApplication() { WindowTitle = tstring("First Instance"); }
  void InitMainWindow() { SetMainWindow( new TFrameWindow(0, WindowTitle.c_str())); }
};

int
OwlMain(int /* argc */, char* /* argv */[])
{
 return TTestApp().Run();
}

When multiple 16-bit instances of this application are open on the desktop, the first one has the title "First Instance" and each subsequent instance has the title "Additional Instance". Note: 16-bit applications are no longer supported by OWLNext.

Because each instance of a 32-bit application is perceived as the first instance of the application, multiple 32-bit copies running at the same time all have the caption "First Instance".

Initializing each new instance

A user can run multiple instances (copies) of an application simultaneously. You can override TApplication::InitInstance() to perform any initialization you need to do for each instance. InitInstance calls InitMainWindow and then creates and shows the main window you set up in InitMainWindow. If you override InitInstance, be sure your new InitInstance calls TApplication::InitInstance. The following example shows how to use InitInstance to load an accelerator table.

 void
 TTestApp::InitInstance()
 {
   TApplication::InitInstance();
   HAccTable = LoadAccelerators(MAKEINTRESOURCE(MYACCELS));
 }

Initializing the main window

By default, TApplication::InitMainWindow() creates a frame window with the same name as the application object. This window is not very useful, because it cannot receive or process any user input. You must override InitMainWindow to create a window object that does process user input. Normally, your InitMainWindow function creates a TFrameWindow or TFrameWindow-derived object and calls the SetMainWindow function, a protected member function of TApplication. SetMainWindow takes one parameter, a pointer to a TFrameWindow object, and returns a pointer to the old main window. (If this is a new application that has not yet set up a main window, the return value is zero). The following example shows a simple application that creates a TFrameWindow object and makes it the main window:

 #include <owl\applicat.h>
 #include <owl\framewin.h>
 using namespace owl;

 class TMyApplication: public TApplication
 {
 public:
   TMyApplication(const tstring& name):TApplication(name) {}
   virtual void InitMainWindow();
 };

 void
 TMyApplication::InitMainWindow()
 {
   SetMainWindow(new TFrameWindow"(0, "My First Main Window"));
 }

 int
 OwlMain(int argc, char* argv[])
 {
   return TMyApplication("Wow!").Run();
 }

When you run this application, the caption bar is titled "My First Main Window," and not "Wow!". The application name passed in the TApplication constructor is used only when you do not provide a main window. Once again, this example doesn't do a lot; there is still no provision for the frame window to process any user input. But once you have derived a window class that does interact with the user, you use the same simple method to display the window.