Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp

Chapter 11 - Working With Applications

Recipes--Applications

The recipes and sample code in this section demonstrate how to create and launch a MacApp application. Figure 11-1 shows a partial class hierarchy for MacApp's application classes, including the TIconEditApplication class from the IconEdit sample application. It also shows some of the macros and initialization routines that are used to launch an application.

Figure 11-1 Application classes, methods, and initialization routines

Recipe--Defining a Subclass of TApplication

To define a subclass of TApplication, you perform these steps:

1. Provide a class definition.
2. Provide constructor and destructor methods.
3. Provide an initialization method.
4. Override the DoMakeDocument method.

The sample code shown in this recipe is from the IconEdit application.

Provide a Class Definition

The definition for your application class should look something like the definition of the TIconEditApplication class:

class TIconEditApplication : public TApplication
{
   MA_DECLARE_CLASS;                // Macro for RTTI info.
   public:
   TIconEditApplication();          // Constructor.
   virtual ~TIconEditApplication(); // Destructor.
   virtual void IIconEditApplication(); // Initialization.
   virtual TDocument* DoMakeDocument(CommandNumber
      itsCommandNumber, TFile* itsFile);// Override.
   // Some methods not shown.
};

Provide Constructor and Destructor Methods

Since the TIconEditApplication class adds no additional fields to TApplication, its constructor and destructor methods are empty. For a recipe that shows nonempty constructor and destructor methods, see "Provide Constructor and Destructor Methods," beginning on page 279 in Chapter 10, "Working With Objects."

Provide an Initialization Method

The initialization method for your application class should perform the following tasks:

• It should call the initialization method of its parent class.
• It should perform any initialization specific to your class that can't be handled safely in a constructor method.

  For example, a constructor should not perform operations that may fail, such as allocating memory. So if your application needs to allocate memory, you do so in the initialization method.

Consider the initialization method for TIconEditApplication:

void TIconEditApplication::IIconEditApplication()
{
   this->IApplication(kFileType, kSignature);
   MA_REGISTER_CLASS(TIconEditView);
}  // IIconEditApplication

The IIconEditApplication method calls IApplication to ensure proper initialization of MacApp. The constants passed to IApplication specify a file type and an application signature.

After calling IApplication, the IIconEditApplication method performs any initialization specific to the application. For TIconEditApplication, that consists entirely of using the MA_REGISTER_CLASS macro to register the TIconEditView class so that the application can create view objects of that type by name or by class ID.

As an example of application-specific initialization, if you don't want your application to open a new document when launched (MacApp's default behavior), include the following line (after calling IApplication):

fLaunchWithNewDocument = FALSE; // No new document at launch.

Override the DoMakeDocument Method

In MacApp, the responsibility for creating documents falls to the application object's DoMakeDocument method. In the TApplication class, that method does nothing, so you must override DoMakeDocument to create the kind of documents your application requires.

The DoMakeDocument method creates and initializes a document object and returns a reference to it. The following is the DoMakeDocument method from the TIconEditApplication class:

TDocument* TIconEditApplication::DoMakeDocument(
                  CommandNumber/*itsCommandNumber*/,
                  TFile*      itsFile)
{
   TIconDocument* anIconDocument;

   // Create and initialize a TIconDocument object.
   anIconDocument = new TIconDocument;
   anIconDocument->IIconDocument(itsFile);

   // Return a reference to the document.
   return anIconDocument;
}

The itsCommandNumber parameter can be used to determine the type of document to create, but it is commented out here because the IconEdit application only creates one kind of document. Your application can set the command number passed to DoMakeDocument by overriding the TApplication::KindOfDocument method. It can also create different kinds of documents based on the command number. For more information, see "Kinds of Documents," beginning on page 169.

Recipe--Launching a Simple Application

To launch a simple application, you perform these steps:

1. Define a subclass of TApplication.
2. Create a main routine.

The sample code shown in this recipe is from the IconEdit application.

Define a Subclass of TApplication

This step is described in "Recipe--Defining a Subclass of TApplication" on page 289. If your application supports PowerTalk mailers, your application class should descend from the TMailingApplication class, a subclass of the TApplication class.

Create a Main Routine

You write a main routine for each MacApp application you create. The main routine performs the following steps:

• It calls InitUMacApp, a macro supplied by MacApp, to initialize the Macintosh Toolbox, initialize MacApp, and perform other initialization tasks.
• It initializes any additional MacApp units used by your application, as well as any application units you may have defined.
• It creates and initializes an instance of your application class.
• It calls the application object's Run method to launch the application and start the application's main event loop.

The following is the main routine from the IconEdit application:

void main()
{
   // Initialize MacApp with 4 calls to MoreMasters.
   InitUMacApp(4);
   // Initialize the printing unit.
   InitUPrinting();

   // Create and initialize an application object.
   TIconEditApplication* anIconEditApplication = 
                        new TIconEditApplication;
   anIconEditApplication->IIconEditApplication();

   // Run the application's main event loop.
   anIconEditApplication->Run();
} // main

The InitUMacApp macro is expanded to a number of calls that perform initialization tasks for MacApp. One of these tasks is to call the MacApp routine InitUMemory, passing the same value that was passed to InitUMacApp (in this case, 4). This value tells the InitUMemory routine how many times to call the Macintosh Toolbox routine MoreMasters. The MoreMasters routine allocates space for a block of master pointers. By calling MoreMasters during MacApp initialization, InitUMacApp ensures that the master pointers are among the first items allocated in the heap, and memory fragmentation is minimized.

Each call to MoreMasters creates a block of 64 master pointers. The number passed to InitUMacApp by your application's main routine should equal the greatest number of dynamically allocated blocks of memory that your application will need at any one time, divided by 64.

The IconEdit application calls the InitUPrinting routine to initialize MacApp's Printing unit. The following code shows how to initialize additional MacApp units to support dialog boxes, drag and drop, floating windows, PowerTalk, and text-edit views:

InitUDialog();
#if qDrag
   if (HasDragManager())
      InitUDragManager();
#endif
InitUFloatWindow();
#if qPowerTalk
   if (HasAOCEToolBox())
      InitUMailer();
#endif
InitUTEView();

These MacApp units are not automatically included in every application. This code uses the compiler flags qDrag, to conditionally include drag-and-drop initialization, and qPowerTalk, to conditionally include PowerTalk initialization. For information on compiler flags and on how to include MacApp units when you build your application, see Appendix A.

The IIconEditApplication method is described in the previous recipe.

The TApplication::Run method checks whether there is enough memory to run the application, calls DoLaunchClipboard to set up the application's Clipboard, and finally calls the application's MainEventLoop method, which looks for incoming events to dispatch.

Recipe--Launching an Application With a Startup Screen

When you launch an application with a startup screen, you can't simply use the InitUMacApp macro. That macro expands into calls to InitUMacApp_Step1, InstallFailureHandler, and InitUMacApp_Step3. To launch your application with a startup screen, you call each of the three routines separately at the appropriate time, making sure to call the InstallFailureHandler routine from within the main routine.

To launch an application with a startup screen, you perform these steps:

1. Create a specialized main routine.
2. Create a routine to display a startup screen.

The sample code shown in this recipe is from the Calc application.

Create a Specialized Main Routine

A main routine that displays a startup screen must break up the standard process of initializing MacApp and launching the application. One way to accomplish this is to write a main routine that performs the following steps:

• It calls the MacApp routine InitUMacApp_Step1, which initializes the Macintosh Toolbox and performs other initialization tasks.
• It calls the MacApp routine InstallFailureHandler, which installs a top-level failure handler for MacApp's failure-handling mechanism.
• It calls the MacApp routine PullApplicationToFront, which makes sure the application is the active application, so it can display a startup screen.
• It calls a routine you write (described in the next section) that displays a startup screen while it completes the initialization of MacApp and creates an application object. Your routine returns the application object it created.
• It calls the application object's Run method to launch the application.

The main routine from the Calc application, shown on the following page, performs each of these steps.

void main()
{
   // Initialize Macintosh Toolbox and validate machine configuration.
   InitUMacApp_Step1();

   // Install permanent outermost failure handler. Note that
   // InstallFailureHandler is implemented as a macro.
   // This MUST be called from main on PowerPC!
   InstallFailureHandler;

   // Make the application active.
   PullApplicationToFront();

   // Call routine to display startup screen while completing
   // the initialization.
   TCalcApplication* aCalcApplication = InitWithSplashScreen();

   // Launch the application's main event loop.
   aCalcApplication->Run();

} // main

Create a Routine to Display a Startup Screen

To display a startup screen, you write a routine that performs the following steps:

• It gets and displays the startup screen.
• It calls the MacApp routine InitUMacApp_Step3 to perform additional MacApp initialization.
• It calls MacApp routines to initialize other MacApp units used by the application (such as the Printing unit).
• It creates and initializes an application object.
• It closes the startup screen.
• It returns the application object.

The InitWithSplashScreen routine from the Calc application demonstrates these steps.

TCalcApplication* InitWithSplashScreen()
{
   TCalcApplication* aCalcApplication = NULL;
   DialogRecord theDialogRecord;
.
   // Show the startup screen.
   if (GetNewCenteredDialog(phSplash,
      (Ptr) &theDialogRecord,(WindowRef) (-1)) != NULL)
   {
      DrawDialog((GrafPort*) &theDialogRecord);
   }
   // Continue initialization, including memory initialization.
   InitUMacApp_Step3(16);

   // Initialize additional units used by the application.
   InitUEditionDocument();
   InitUTEView();
   InitUGridView(); 
   InitUPrinting();

   // Create the application object and initialize it.
   aCalcApplication = new TCalcApplication;
   aCalcApplication->ICalcApplication();

   // Remove the startup screen and dispose of it.
   CloseDialog((DialogRef) &theDialogRecord);
   DisposeIfHandle(theDialogRecord.items);

   // Return the application object we created.
   return aCalcApplication;

} // InitWithSplashScreen

The constant phSplash identifies a dialog resource in the file Calc.r.