doInitManagers

doInitManagers grows the application heap, creates a block of master pointers,
initialises the system software managers, and sets the cursor to the standard arrow
shape.

Note that the function name is somewhat of a misnomer in that it does more than
initialise the system software managers.  However, since growing the heap, creating
additional master pointer blocks, and setting the standard arrow cursor shape are
invariably part of an application's setting up process, it is convenient to attend to
those matters within the doInitManagers function.  This practice will continue in all
other demonstration programs.

The call to MaxApplZone is really not required for this simple program.  However, it
should be the first call in any serious application.  The call grows the heap immediately
to the maximum permissible size, assisting in the prevention of heap fragmentation,
reducing the number of blocks which the Memory Manager has to purge when satisfying a
memory request and speeding up memory allocation operations.

The call to MoreMasters to allocate a block of master pointers is really not required in
this simple program because the Operating System automatically allocates one block of
master pointers at application launch.  However, in larger applications where more than
64 master pointers are required, the call, or calls, to MoreMasters should be made here
so that all master pointer (nonrelocatable) blocks are located at the bottom of the heap. 
This will assist in preventing heap fragmentation.

The next six lines initialise certain system software managers.  Not all of the data
structures and variables inititialised by these calls will be used by this simple
program; however, any serious application will require the full initialisation shown.  It
is also relevant that some managers require the use of information in other managers, so
those other managers need to be initialised at least for that purpose.  Some explanatory
notes on the various calls are as follows:

*  InitGraf initialises the QuickDraw global variables.  The first element in the
   QuickDraw global data area is a pointer (thePort) to the current graphics port.
   Because it is the first QuickDraw global, passing its address to InitGraf tells 
   QuickDraw where all the other QuickDraw globals are located.  Other QuickDraw globals
   initialised by InitGraf are:

*  The pattern variables qd.white, qd.black, qd.gray, qd.ltGray, qd.dkGray.

*  qd.arrow, which contains the standard cursor arrow shape and which can be passed as an
   argument to QuickDraw's cursor functions.

*  qd.screenBits, a data structure which describes the main screen.  The field 
   screenBits.bounds contains a rectangle which encloses the main screen.

*  qd.randSeed, which is used to seed the random number generator.

Note:  The header file Quickdraw.h defines the following data type:

     struct QDGlobals
     {
       char      privates[76];
       long      randSeed;
       BitMap    screenBits;
       Cursor    arrow;
       Pattern   dkGray;
       Pattern   ltGray;
       Pattern   gray;
       Pattern   black;
       Pattern   white;
       GrafPtr   thePort;
     };
     typedef struct QDGlobals QDGlobals;
     extern QDGlobals qd;

In the 680x0 environment, the runtime libraries define the QuickDraw global variable qd. 
There is no need for your application to do this.

*  InitFont initialises the Font Manager and loads the system font into memory.  Since
   the Window Manager uses the Font Manager to draw the window's title, etc., InitFonts
   must be called before InitWindows. Also, it must be called after InitGraf.

*  InitWindows initialises the Window Manager port.  It must be called after InitGraf and
   InitFonts.  It draws the familiar rounded rectangle desktop with an empty menu bar at
   the top.  The fill pattern used is the resource whose resource ID is represented by 
   the constant deskPatID.  (If a different fill pattern is required, it can be specified
   in the application's resource file.)  The call establishes a nonrelocatable block (the
   Window Manager port) in the application heap.

*  InitMenus allocates heap storage for the menu list and draws an empty menu bar.  (For
   some unknown reason, InitWindows and InitMenus both draw the menu bar.)  InitMenus 
   must be called after InitGraf, InitFonts and InitWindows.

*  TEInit initialises TextEdit, the Text editing manager, by allocating an internal 
   handle for the TextEdit scrap (not the same as the "desk scrap" maintained by the Desk
   Manager).  It should be called even if the application does not explicitly use 
   TextEdit functions, since it ensures that dialog boxes and alert boxes work correctly.

*  InitDialogs initialises the Dialog Manager and optionally installs a function to get 
   control after a fatal system error.  It installs the standard sound procedure (for
   alerts) and sets all text replacement parameters to empty strings (see the function
   ParamText).

InitCursor sets the cursor shape to the standard arrow cursor and sets the cursor level
to 0, making it visible.  (The 68-byte Cursor structure for the standard arrow cursor can
be found in the QuickDraw data area.)

doNewWindow creates a window.

NewPtr is used to allocate a nonrelocatable block of memory for the window structure.  If
the call is not successful, the system alert sound is played and the program is
terminated by a call to ExitToShell, which releases the heap and hands control to the
Finder.  (Note that error handling here, and in the rest of the program, is thus somewhat
rudimentary.  Note also that SysBeep's parameter is nowadays ignored, but must be
included for historical reasons.)

The call to GetNewCWindow creates a window using the 'WIND' template resource  specified
in the first parameter, and using the pointer to the nonrelocatable block already
allocated for the window structure as the second parameter.  (The third parameter tells
the Window Manager to open the window in front of all other windows.)  The type, size,
location, appearance, title and visibility of the window are all established by the
'WIND' resource.

Recall that, as soon as the data from the 'WIND' template resource is copied to the
window structure during the creation of the window, the nonrelocatable block occupied by
the template will automatically be marked as purgeable.

The call to SetPort makes the new window's graphics port the current port for drawing
operations.  The call to TextFont at sets the font for that port to the standard system
default font (Chicago or Charcoal, depending on the setting in the Appearance control
panel).

doDrawPictAndString draws a picture and some text strings in the window.

GetPicture reads in the 'PICT' resource corresponding to the ID specified in the
GetPicture call.  If the call is not successful, the system alert sound is played and the
program terminates.

The SetRect call assigns values to the left, top, right and bottom fields of a Rect
variable.  This Rect is required for a later call to DrawPicture.

The basic rules applying to the use of purgeable resources are to load it, immediately
make it unpurgeable, use it immediately, and immediately make it purgeable.  Accordingly,
the HNoPurge call makes the relocatable block occupied by the resource unpurgeable, the
DrawPicture call draws the picture in the window's graphics port, and the HPurge call
makes the relocatable block purgeable again.

Note that, because HNoPurge and HPurge expect a parameter of type Handle, pictureHdl (a
variable of type PicHandle) must be cast to a variable of type Handle.

GetString then reads in the specified 'STR ' resource.  Once again, if the call is not
successful, the system alert sound is played and the program terminates.  MoveTo moves
the graphics "pen" to an appropriate position before DrawString draws the string in the
window's graphics port.  (Since the 'STR ' resource, unlike the 'PICT' resource, does not
have the purgeable bit set, there is no requirement to take the precaution of a call to
HNoPurge in this case.)

Note the parameter in the call to DrawString.  stringHdl, like any handle, is a pointer
to a pointer.  It contains the address of a master pointer which, in turn, contains the
address of the data.  Dereferencing the handle once, therefore, get the required
parameter for DrawString, which is a pointer to a string.

The calls to ReleaseResource release the 'PICT' and 'STR ' resources.  These calls
release the memory occupied by the resources and set the associated handles in the
resource map in memory to NULL.

The ResError call returns the error code of the most recent resource-related operation. 
If the call returns noErr (indicating that no error occurred as a result of the most
recent call by a Resource Manager function), some advisory text is drawn in the graphics
port.

The next six lines examine the result of the most recent call to a memory manager
function and draw some advisory text if no error occurred as a result of that call.

Note that the last two calls to DrawString utilise "hard-coded" strings.  This sort of
thing is discouraged in the Macintosh programming environment.  Such strings should
ordinarily be stored in a 'STR#' (string list) resource rather than hard-coded into the
source code.  The \p token causes the compiler to compile these strings as Pascal
strings.

As stated in the Preface, when it comes to the system software, the 
ghost of the Pascal language forever haunts the C programmer.  For example, a 
great many system software functions take Pascal strings as a required 
parameter, and some functions return Pascal strings.

Pascal and C strings differ in their formats.  A C string comprises the 
characters followed by a terminating 0 (or NULL byte):

+---+---+---+---+---+---+---+---+---+---+
| M | Y |   | S | T | R | I | N | G | 0 |
+---+---+---+---+---+---+---+---+---+---+

In a Pascal string, the first byte contains the length of the string, and the 
characters
follow that byte:

+---+---+---+---+---+---+---+---+---+---+
| 9 | M | Y |   | S | T | R | I | N | G |
+---+---+---+---+---+---+---+---+---+---+

Not surprisingly, then, Pascal strings are often referred to as 
"length-prefixed" strings.

In Chapter 3, you will encounter the data type Str255.  Str255 is the C name 
for a Pascal-style string capable of holding up to 255 characters.  As you 
would expect, the first byte of a Str255 holds the length of the string and 
the following bytes hold the characters of the string.

Utilizing 256 bytes for a string will simply waste memory in many cases.  
Accordingly, the header file Types.h defines the additional types Str63, 
Str32, Str31, Str27, and Str15, as well as the Str255 type:-

    typedef unsigned char Str255[256];
    typedef unsigned char Str63[64];
    typedef unsigned char Str32[33];
    typedef unsigned char Str31[32];
    typedef unsigned char Str27[28];
    typedef unsigned char Str15[16];
    
Note, then, that a variable of type Str255 holds the address of an array of 
256 elements, each element being one byte long.

As an aside, in some cases you may want to use C strings, and use standard C 
library functions such as strlen, strcpy, etc., to manipulate them.  
Accordingly, be aware that functions exist (C2PStr, P2CStr) to convert a 
string from one format to the other.

You may wish to make a "working" copy of the SysMemRes demonstration program 
file package and, using the working copy of the source code file SysMemRes.c, 
replace the function doDrawPictAndString with the following, compile-link-run, 
and note the way the second and third strings appear in the window.

    void  doDrawPictAndString(void)
    {
      Str255  string1 = "\pIs this a Pascal string I see before me?";
      Str255  string2 = "Is this a Pascal string I see before me?";
      Str255  string3 = "%s this a Pascal string I see before me?";
      Str255  string4;
      SInt16  a;

      // Draw string1    

      MoveTo(30,100);
      DrawString(string1);

      // Change the length byte of string1 and redraw

      string1[0] = (char) 23;
      MoveTo(30,120);
      DrawString(string1);

      // Leave the \p token out at your peril
      // I (ASCII code 73) is now interpreted as the length byte

      MoveTo(30,140);
      DrawString(string2);

      // More peril:-  % (ASCII code 37) is now the length byte

      MoveTo(30,160);
      DrawString(string3);

      // A hand-built Pascal string

      for(a=1;a<27;a++)
        string4[a] = (char) a + 64;

      string4[0] = (char) 26;

      MoveTo(30,180);
      DrawString(string4);

      // But is there a Mac OS function to draw the C strings correctly?

      MoveTo(30,200);
      DrawText(string2,0,40);  // Look it up in your on-line reference
    }