ADVERTISEMENT

The About Box

By Jack Edward Chor, Belleville, IL

This article presents a shell for creating a consistent and informative About dialog in your Macintosh™ applications. Although it is not the esoteric stuff of which Turing Awards are made, this shell does demonstrate the use of PICT resources and userItems in dialogs, the use of a filterProc function in a ModalDialog call, the wealth of information that is contained in a single call to SysEnvirons, and the ease with which the Sound Manager can be worked into dialogs. An example of the About dialog created by this shell is shown in Figure 1.

Figure 1

The dialog shown in Figure 1 consists of only two items. The first item is a PICT resource which draws everything shown in the dialog except the system information contained in the lower right-hand corner. The second item is a user item which draws the system information as returned from a SysEnvirons call.

The program was developed in Lightspeed™ Pascal and consists of six units. The build order and segmentation of the program are shown in Figures 2 and 3. The units used in the program are as follows:

1. xText. This is the interface file for the Text.lib library used in the program. A complete listing of the library is included in this article. The library consists of six short routines to display strings and integers in three different formats: left-justified, centered, and right-justified. There are two additional routines that get and set text-related grafPort parameters. All of these routines operate on the current grafPort.

2. Sound.p. This is the standard Sound Manager interface file included with Lightspeed Pascal.

3. About.Glob. This contains the global constants and variables used in the program.

4. About.Init. This contains the initialization routines for the program. This unit is contained in a separate segment so that it can be unloaded immediately after initialization is completed.

5. About.About. This contains the code for creating, displaying, and destroying the About dialog.

6. About.Main. This contains the event loop and menu dispatcher for the program. Since the purpose of this program is to merely illustrate the About dialog, the main unit is a bare-bones implementation of the classic Macintosh event loop.

At startup, the main program calls InitAbout to do initialization. Among other things, this routine loads the global variable AboutWorld with the SysEnvRec of the machine on which the program is running. In a fully functional program, a prudent programmer would screen AboutWorld at this point to determine whether the hardware and software configuration of the machine is acceptable to the program. After completing the initialization routine, UnloadSeg is called to unlock the initialization segment and free up the memory occupied by the initialization code. DoAboutBox is then called with the Boolean parameter PlayAboutSound set to TRUE. This displays the About dialog and tells the routine to load and play the ‘snd ‘ resource associated with the dialog box. Although the example program plays a melody on the note synthesizer, the sounds that can be played are limited only by the imagination of programmer and the capabilities of the Sound Manager. At the conclusion of the About melody, the About dialog is disposed and the program enters its event loop. The event loop looks for menu or command-key events and dispatches them through the DecodeMenu procedure. The program will terminate upon selection of the “Quit” menu item.

Figure 2

Figure 3

When DoAboutBox is called, the procedure first stores the current grafPort in the local variable oldPort. It then initializes the display rectangle for the dialog’s userItem. To display the system information retrieved from the SysEnvirons call in an understandable format, the numeric and Boolean fields of the SysEnvRec must be converted to character strings. This is done by the GetEnvStr procedure. GetEnvStr takes a SysEnvRec as a value parameter and returns an equivalent EnvStrList as a variable parameter. An EnvStrList is merely an array of seven strings, each representing an item of system information to be displayed in the About dialog. The names of the various Macintosh™ models, processors, and keyboards are stored in STR# resources. Because of peculiarities in the numeric values returned in the machineType and keyBoardType fields of the SysEnvRec, a one-to-one mapping between values of these fields and their corresponding indexed strings is not possible. Consequently, the numeric values must be modified slightly in order to get the correct index into the appropriate STR# resource. Also, the systemVersion field of the SysEnvRec returns the version number in a unique Apple format. As a result, a string conversion must be made. This is done in the GetSysVersStr function. Finally, in order to get the amount of free memory remaining, a call is made to PurgeSpace. This returns the total amount of memory which could be obtained by a general purge without actually doing the purge. It should be noted that this call is only available under the 128K ROM and can be replaced (less accurately) by the 64K ROM call FreeMem.

After the EnvStrList is returned from GetEnvStr, GetNewDialog is called to load the About dialog box into memory. When creating the dialog box in your resource editor, you should remember to make the dialog invisible. This will allow you to add the userItem to the dialog before the dialog box is actually displayed on the screen. After GetNewDialog loads the dialog into memory, a SetPort call makes the dialog the current grafPort. A SetDItem call is then used to place the userItem into the dialog’s item list. The userItem in the About dialog is a procedure called EnvItem. The only thing that EnvItem does is draw the strings in the EnvStrList in a column at the location specified in the constant declaration of the procedure. Since all of the dialog’s items are now in place, a call to ShowWindow is all that is needed to display it.

If PlayAboutSound is TRUE, this means that the calling program wants DoAboutBox to play the ‘snd ‘ resource associated with the dialog box. For some reason unbeknownst to your humble narrator, if the dialog box is not manually updated with the BeginUpdate-UpdtDialog-EndUpdate code sequence, the ‘snd ‘ resource will be played before anything is drawn in the dialog box. It should be noted that UpdtDialog is a 128K ROM call which can be replaced by the 64K ROM call DrawDialog. After the dialog box is drawn, a GetResource call loads the ‘snd ‘ and SndPlay plays it. After the sound is played, ReleaseResource is called to deallocate the memory used by the ‘snd ‘ resource. After the resource is released, DisposDialog makes the dialog disappear. If you want your dialog to hang around after the sound is played, simply remove the ELSE construct in the IF-THEN statement. If no sound is to be played, the sound routine is skipped and ModalDialog is called. The filterProc for the ModalDialog call is MouseKeyFilter. As its name implies and its code verifies, this filterProc waits for a mouseDown or keyDown event to occur. When one occurs, the filterProc function returns a nonzero value. This causes the the program to leave the REPEAT-UNTIL construct and call DisposDialog. Finally, SetPort is called to restore the grafPort which was current immediately prior to the DoAboutBox call.

Listing:  xText.p

UNIT xText;
INTERFACE
 PROCEDURE SetPortText (tFont, tSize, tMode: 
 INTEGER; tFace: Style);
 PROCEDURE GetPortText (VAR tFont, tSize, tMode: 
 INTEGER; VAR tFace: Style);
 PROCEDURE WriteTextAt (newH, newV: INTEGER;
 regStr: str255);
 PROCEDURE WriteNumAt (newH, newV: INTEGER;
 regNum: LONGINT);
 PROCEDURE WriteRJTextAt (newH, newV: INTEGER;
 regStr: str255);
 PROCEDURE WriteRJNumAt (newH, newV: INTEGER;
 regNum: LONGINT);
 PROCEDURE WriteCtrTextAt (newH, newV: INTEGER;
 regStr: str255);
 PROCEDURE WriteCtrNumAt (newH, newV: INTEGER;
 regNum: LONGINT);

IMPLEMENTATION
 CONST
 div2 = 1;
 VAR
 numStr: str255;

 PROCEDURE SetPortText;
 BEGIN
 WITH thePort^ DO
 BEGIN
 txFont := tFont;
 txSize := tSize;
 txMode := tMode;
 txFace := tFace;
 END;
 END;

 PROCEDURE GetPortText;
 BEGIN
 WITH thePort^ DO
 BEGIN
 tFont := txFont;
 tSize := txSize;
 tMode := txMode;
 tFace := txFace;
 END;
 END;

 PROCEDURE WriteTextAt;
 BEGIN
 WITH thePort^.pnLoc DO
 BEGIN
 h := newH;
 v := newV;
 END;
 DrawString(regStr);
 END;

 PROCEDURE WriteNumAt;
 BEGIN
 NumToString(regNum, numStr);
 WriteTextAt(newH, newV, numStr);
 END;

 PROCEDURE WriteRJTextAt;
 BEGIN
 newH := newH - StringWidth(regStr);
 WriteTextAt(newH, newV, regStr);
 END;

 PROCEDURE WriteRJNumAt;
 BEGIN
 NumToString(regNum, numStr);
 WriteRJTextAt(newH, newV, numStr);
 END;

 PROCEDURE WriteCtrTextAt;
 BEGIN
 newH := newH - BSR(StringWidth(regStr), div2);
 WriteTextAt(newH, newV, regStr);
 END;

 PROCEDURE WriteCtrNumAt;
 BEGIN
 NumToString(regNum, numStr);
 WriteCtrTextAt(newH, newV, numStr);
 END;

END.

Listing:  About.Glob

UNIT Glob;
INTERFACE
 CONST
 AboutMenu = 128;
 AboutItem = 1;
 QuitItem = 3;

 fSize9 = 9;

 toFront = -1;
 VAR
 AboutEvent: EventRecord;
 AboutWorld: SysEnvRec;

 AboutM: MenuHandle;

 TimeToQuit: BOOLEAN;
IMPLEMENTATION
END.

Listing:  Init.p

UNIT Init;
INTERFACE
 USES
 Glob;

 PROCEDURE InitAbout;

IMPLEMENTATION
 PROCEDURE InitAbout;
 CONST
 EnvReqNum = 2;
 VAR
 envErr: OSErr;
 BEGIN
 InitCursor;

 AboutM := GetMenu(AboutMenu);
 InsertMenu(AboutM, 0);
 DrawMenuBar;

 envErr := SysEnvirons(EnvReqNum, AboutWorld);

 TimeToQuit := FALSE;
 END;
END.

Listing:  About.About

UNIT About;
INTERFACE
 USES
 xText, Sound, Glob;

 PROCEDURE DoAboutBox (PlayAboutSound: BOOLEAN);

IMPLEMENTATION
 CONST
 macModel = 1;
 macSys = 2;
 macProc = 3;
 macFP = 4;
 macColorQD = 5;
 macKey = 6;
 macMemFree = 7;
 TYPE
 EnvStrList = ARRAY[macModel..macMemFree] OF str255;
 VAR
 envStr: EnvStrList;

 FUNCTION MouseKeyFilter (whichD: DialogPtr; VAR theEvent: EventRecord; 
VAR itemHit: INTEGER): BOOLEAN;
 CONST
 MKHit = 1;
 BEGIN
 MouseKeyFilter := FALSE;
 IF theEvent.what IN [keyDown, mouseDown] THEN
 BEGIN
 itemHit := MKHit;
 MouseKeyFilter := TRUE;
 END;
 END;

 PROCEDURE GetEnvStr (envWorld: SysEnvRec;
 VAR macEnvStr: EnvStrList);
 CONST
 MacNamesID = 1001;
 MacProcID = 1002;
 MacKeysID = 1003;

 unkS = ‘Unknown’;
 availS = ‘Available’;
 notAvailS = ‘Not Available’;

 PlusKbd = ‘Macintosh Plus’;
 XLKbd = ‘XL + Keypad’;

 oldM = 3;
 newM = 2;

 envMacIIcx = 6; {New constants}
 envSE30 = 7;
 envPortable = 8;
 envMacIIci = 9;

 env68030 = 4;

 envPortADBKbd = 6;
 envPortISOADBKbd = 7;
 envStdISOADBKbd = 8;
 envExtISOADBKbd = 9;
 VAR
 pTotal, pContig: LONGINT;
 FUNCTION GetSysVersStr (versNum: INTEGER): str255;
 CONST
 MajRevTenMask = $0000F000;
 MajRevOneMask = $00000F00;
 MinRevNumMask = $000000F0;
 BugFixNumMask = $0000000F;
 MajRevTenRot = 12;
 MajRevOneRot = 8;
 MinRevNumRot = 4;
 BugFixNumRot = 0;
 TenPlace = 10;
 VAR
 majRev, minRev, bugFix: LONGINT;
 decStr: str255;

 PROCEDURE AddNumToString (addNum: INTEGER;
 VAR numStr: str255; addDecPt: BOOLEAN);
 VAR
 tempStr: str255;
 BEGIN
 NumToString(addNum, tempStr);
 numStr := concat(numStr, tempStr);
 IF addDecPt THEN
 numStr := concat(numStr, ‘.’);
 END;

 BEGIN
 decStr := ‘’;
 majRev := BSR(BAND(versNum, MajRevTenMask),
 MajRevTenRot) * TenPlace;
 majRev := majRev + BSR(BAND(versNum, 
 MajRevOneMask), MajRevOneRot);
 minRev := BSR(BAND(versNum, MinRevNumMask), MinRevNumRot);
 bugFix := BSR(BAND(versNum, BugFixNumMask),
 BugFixNumRot);
 AddNumToString(majRev, decStr, TRUE);
 IF bugFix > 0 THEN
 BEGIN
 AddNumToString(minRev, decStr, TRUE);
 AddNumToString(bugFix, decStr,  FALSE);
 END
 ELSE
 AddNumToString(minRev, decStr, FALSE);
 GetSysVersStr := decStr;
 END;

 BEGIN
 WITH envWorld DO
 BEGIN
 CASE machineType OF
 envMac, envXL: 
 GetIndString(macEnvStr[macModel]
 , MacNamesID, machineType + oldM);
 env512KE..envMacIIci: 
 GetIndString(macEnvStr[macModel]
 , MacNamesID, machineType + newM);
 OTHERWISE
 macEnvStr[macModel] := unkS;
 END;
 macEnvStr[macSys] :=   GetSysVersStr(systemVersion);
 CASE processor OF
 env68000..env68030: 
 GetIndString(macEnvStr[macProc],
 MacProcID, processor);
 OTHERWISE
 macEnvStr[macProc] := unkS;
 END;
 IF hasFPU THEN
 macEnvStr[macFP] := availS
 ELSE
 macEnvStr[macFP] := notAvailS;
 IF hasColorQD THEN
 macEnvStr[macColorQD] := availS
 ELSE
 macEnvStr[macColorQD] := notAvailS;
 CASE keyBoardType OF
 envUnknownKbd: 
 IF machineType = envXL THEN
 macEnvStr[macKey] := XLKbd
 ELSE
 macEnvStr[macKey] :=   PlusKbd;
 envMacKbd..envExtISOADBKbd: 
 GetIndString(macEnvStr[macKey],
 MacKeysID, keyBoardType);
 OTHERWISE
 macEnvStr[macKey] := unkS;
 END;
 PurgeSpace(pTotal, pContig);
 NumToString(pTotal, macEnvStr[macMemFree]);
 END;
 END;

 PROCEDURE EnvItem (whichW: WindowPtr; whichItem: INTEGER);
 CONST
 envSpace = 12;
 envRMar = 364;
 envVStart = 210;
 VAR
 vCtr, currVLine: INTEGER;
 BEGIN
 SetPortText(geneva, fSize9, srcOr, []);
 currVLine := envVStart;
 FOR vCtr := macModel TO macMemFree DO
 BEGIN
 WriteRJTextAt(envRMar, currVLine, envStr[vCtr]);
 currVline := currVline + envSpace;
 END;
 END;

 PROCEDURE DoAboutBox;
 CONST
 AboutBoxID = 1001;
 AboutSoundID = 1001;
 infoItem = 2;
 drT = 201;
 drL = 279;
 drB = 284;
 drR = 371;
 noHit = 0;
 VAR
 AboutD: DialogPtr;
 AboutSnd: Handle;
 oldPort: GrafPtr;
 dispRect: Rect;
 itemHit: INTEGER;
 sndErr: OSErr;
 BEGIN
 GetPort(oldPort);
 WITH dispRect DO
 BEGIN
 left := drL;
 top := drT;
 right := drR;
 bottom := drB;
 END;
 GetEnvStr(AboutWorld, envStr);
 AboutD := GetNewDialog(AboutBoxID, NIL,
 DialogPtr(toFront));
 SetPort(AboutD);
 SetDItem(AboutD, infoItem, userItem,
 Handle(@EnvItem), dispRect);
 ShowWindow(AboutD);
 IF PlayAboutSound THEN
 BEGIN
 BeginUpdate(AboutD);
 UpdtDialog(AboutD, AboutD^.visRgn);
 EndUpdate(AboutD);
 AboutSnd := GetResource(‘snd ‘, AboutSoundID);
 sndErr := SndPlay(NIL, AboutSnd, FALSE);
 ReleaseResource(AboutSnd);
 END
 ELSE
 REPEAT
 ModalDialog(@MouseKeyFilter, itemHit);
 UNTIL itemHit <> noHit;
 DisposDialog(AboutD);
 SetPort(oldPort);
 END;
END.

Listing:  About.Main

PROGRAM AboutDemo;
 USES
 Glob, Init, About;
 VAR
 clickW: WindowPtr;
 keyChar: CHAR;
 PROCEDURE DecodeMenu (rawMenu: LONGINT);
 VAR
 theMenu, theItem: INTEGER;
 BEGIN
 theMenu := HiWord(rawMenu);
 IF theMenu = AboutMenu THEN
 BEGIN
 theItem := LoWord(rawMenu);
 CASE theItem OF
 AboutItem: 
 DoAboutBox(FALSE);
 QuitItem: 
 TimeToQuit := TRUE;
 END;
 HiliteMenu(0);
 END;
 END;

BEGIN
 InitAbout;
 UnloadSeg(@InitAbout);
 DoAboutBox(TRUE);
 REPEAT
 IF GetNextEvent(EveryEvent, AboutEvent) THEN
 WITH AboutEvent DO
 CASE AboutEvent.what OF
 mouseDown: 
 IF FindWindow(where, clickW) =
 inMenuBar THEN
 DecodeMenu(MenuSelect(where));
 keyDown: 
 BEGIN
 keyChar := chr(BAND(message, CharCodeMask));
 IF (BAND(modifiers, cmdKey)
 <> 0) AND (what <> autoKey) 
 THEN
 DecodeMenu(MenuKey(keyChar));
 END;
 END;
 UNTIL TimeToQuit;
END.