Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 6 - Message Manager / Using the Message Manager

Allocating Memory for and Disposing of Global Data

You can use the NewMessageGlobals function to request and allocate memory for globals. You should only call this function while your application is performing a message override.

You should always initialize your global data from a function other than the one in which you call the NewMessageGlobals function. Otherwise, your development environment may generate code with bad data references.

Listing 6-1 gives an example of using the NewMessageGlobals function to create an A5 world from an MPW programming environment.

Listing 6-1 Creating an A5 world for global data

gxShape  gMyShape;
Handle   gMyHandle;

OSErr MyInitGlobalData()
{
   OSErr err;
   gMyShape = nil;
   gMyHandle = TempNewHandle(1024, &err);
   return err;
}

OSErr MyInitialize()
{
   OSErr err;

/*
   Create an A5 world, and initialize the
   global data.
*/
   err = NewMessageGlobals(A5Size(), A5Init);

   if (!err) err = MyInitGlobalData();
   
   return err;
}

The MyInitalize function is the override for the GXInitialize message. The MyInitialize function first sets up an A5 world, as required if an extension is going to use global data. In this case the global data is the MyShape structure. Once you create the A5 world by calling the NewMessageGlobals function, your global data will be valid whenever your printing extension or printer driver is called. Once the NewMessageGlobals function has been called, the extension or driver can initialize its global data. In this example, the code uses a function called MyInitGlobalData to do this.

If you have allocated memory for your globals using the NewMessageGlobals function, you must use the DisposeMessageGlobals function to dispose of the globals and deallocate their memory blocks when they are no longer needed.

Note that DisposeMessageGlobals does not dispose of data and handles. These must be disposed of by your code. First, you deallocate any memory that you have allocated and then let QuickDraw GX deallocate memory that it has allocated for your global data.

Listing 6-2 shows how to dispose of global data and deallocate the memory that was allocated in Listing 6-1.

Listing 6-2 Disposing of global data and deallocating memory

OSErr MyShutDown()
{/* Dispose of our global data */
   if (gMyHandle != nil)
      DisposHandle(GMyHandle);
/* dispose of the A5 world that was created in MyInitialize */
   DisposeMessageGlobals();
   return noErr;
}

The NewMessageGlobals function is described on page 6-17. The DisposeMessageGlobals function is described on page 6-18.

Global data is discussed in the section "Global Data Storage for Printing Extensions and Printer Drivers" beginning on page 6-7.