TweetFollow Us on Twitter

About Box
Volume Number:7
Issue Number:1
Column Tag:Programmer's Workshop

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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

The best scanner app on mobile
People always say that the best camera is the one you have with you. Well, the same is true with scanners, and your phone can be a pretty great tool for scanning receipts and other documents while you're on the go. [Read more] | Read more »
MARVEL Avengers Academy guide - How to g...
MARVEL Avengers Academy lets you build your own superhero school and fill it with heroes from the Marvel universe. It can be a little slow going to get your school's attendance up though, so we've gathered together somesome tips to help you do this... | Read more »
Shadow Blade: Reload guide - How to hack...
Shadow Blade: Reload is the kind of action-platformer that would have happily sucked up hours of your time on a console a few years back.Now, you can take it with you wherever you go, and its mobile conversion is not too shabby at all. To help you... | Read more »
Tomb of the Mask guide - How to increase...
Tomb of the Mask is a great endless arcade game from Happymagenta in which quick reflexes and a persistent attitude can go a long way toward earning a top score. Check out these tips to see if you can give yourself an edge on the leaderboards. [... | Read more »
Smooth Operator! (Games)
Smooth Operator! 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Smooth Operator is a weird, weird two-player kissing game. Squeeze in for 2 player fun on a single iPad, creating awkward... | Read more »
Sinless: Remastered (Games)
Sinless: Remastered 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: | Read more »
_PRISM Guide - How to solve those puzzle...
_PRISM is a rather delightful puzzle game that’s been tailor made for touch screens. While part of the fun is figuring things out as you go along, we thought we’d offer you a helping hand at getting in the right mindset. Don’t worry about messing... | Read more »
Fractal Space (Games)
Fractal Space 1.3.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.3.1 (iTunes) Description: Live the memorable experience of Fractal Space, a unique first person adventure & puzzle game by Haze Games! Will you... | Read more »
Set off on an adventure through the Cand...
Like match three puzzlers? If so, Jelly Blast, the innovative iOS and Android game which launched last year, is worth a look. Jelly Blast sees you head off on an epic adventure through the Candy Kingdom with your friends Lily, Mr. Hare, and Mr.... | Read more »
Ellipsis - Touch. Explore. Survive. (...
Ellipsis - Touch. Explore. Survive. 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

cb Hardcase – Handmade and Premium Protective...
Baden-Baden, Germany based company cb innovations has introduced the new cb Hardcase for iPhone. Featuring fine Italian Premium leather that makes for a unique look and feel, the cb Hardcase... Read more
Sale! B&H Photo offers 12-inch Retina Mac...
B&H Photo has 12″ Retina MacBooks on sale for $300 off MSRP for a limited time. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Gray Retina MacBook: $999 $300 off MSRP - 12″ 1.... Read more
App Annie Reveals Future of the App Economy:...
App Annie, a San Francisco based mobile app data and insights platform, has launched its first comprehensive app economy forecast. This new offering will provide brands, agencies, investors and app... Read more
Apple restocks Certified Refurbished Mac mini...
Apple has restocked Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $... Read more
What iPad Pro Still Needs To Make It Truly Pr...
I love my iPad Air 2. So much that I’m grudgingly willing to put up with its compromises and limitations as a production tool in order to take advantage of its virtues. However, since a computer for... Read more
21-inch 3.1GHz 4K on sale for $1399, $100 off...
B&H Photo has the 21″ 3.1GHz 4K iMac on sale $1399 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $100 off MSRP: - 21″ 3.1GHz 4K iMac (MK452LL/A): $... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
Save up to $240 with Apple Certified Refurbis...
Apple is now offering Certified Refurbished 12″ Retina MacBooks for up to $240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
Apple refurbished Time Capsules available for...
Apple has certified refurbished Time Capsules available for $120 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $179, $120 off - 3TB... Read more

Jobs Board

Infrastructure Engineer - *Apple* /Mac - Rem...
…part of a team Requires proven problem solving skills Preferred Additional: Apple Certified System Administrator (ACSA) Apple Certified Technical Coordinator (ACTC) Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the largest premier retailer of Apple products in the nation. In order to support our growing customer base, we are currently looking for a driven Read more
*Apple* Reporter - Business Insider, Inc. (U...
Business Insider is looking for a reporter to cover Apple , the biggest and arguably most important company in tech. As our primary Apple reporter, you will: * Read more
Infrastructure Engineer - *Apple* /Mac - Rem...
…part of a team Requires proven problem solving skills Preferred Additional: Apple Certified System Administrator (ACSA) Apple Certified Technical Coordinator (ACTC) Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.