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 beginner's guide to Warbits
Warbits is a turn-based strategy that's clearly inspired by Nintendo's Advance Wars series. Since turn-based strategy games can be kind of tricky to dive into, see below for a few tips to help you in the beginning. Positioning is crucial [Read... | Read more »
How to upgrade your character in Spellsp...
So you’ve mastered the basics of Spellspire. By which I mean you’ve realised it’s all about spelling things in a spire. What next? Well you’re going to need to figure out how to toughen up your character. It’s all well and good being able to spell... | Read more »
5 slither.io mash-ups we'd love to...
If there's one thing that slither.io has proved, it's that the addictive gameplay of Agar.io can be transplanted onto basically anything and it will still be good fun. It wouldn't be surprising if we saw other developers jumping on the bandwagon,... | Read more »
How to navigate the terrain in Sky Charm...
Sky Charms is a whimsical match-'em up adventure that uses creative level design to really ramp up the difficulty. [Read more] | Read more »
Victorious Knight (Games)
Victorious Knight 1.3 Device: iOS Universal Category: Games Price: $1.99, Version: 1.3 (iTunes) Description: New challenges awaits you! Experience fresh RPG experience with a unique combat mechanic, packed with high quality 3D... | Read more »
Agent Gumball - Roguelike Spy Game (Gam...
Agent Gumball - Roguelike Spy Game 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Someone’s been spying on Gumball. What the what?! Two can play at that game! GO UNDERCOVERSneak past enemy... | Read more »
Runaway Toad (Games)
Runaway Toad 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It ain’t easy bein’ green! Tap, hold, and swipe to help Toad hop to safety in this gorgeous new action game from the creators of... | Read more »
PsyCard (Games)
PsyCard 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: From the makers och Card City Nights, Progress To 100 and Ittle Dew PSYCARD is a minesweeper-like game set in a cozy cyberpunk... | Read more »
Sago Mini Robot Party (Education)
Sago Mini Robot Party 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: -- Children's Technology Review Editor's Choice -- | Read more »
Egz – The Origin of the Universe (Games...
Egz – The Origin of the Universe 1.0.2 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.2 (iTunes) Description: ►►► Special offer until 2nd may : get the game at 2.99€ instead of 3.99€ ! ◄◄◄ Egz is a mesmerizing mix... | Read more »

Price Scanner via MacPrices.net

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
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon.com has the 15″ 2.2GHz Retina MacBook Pro on sale for $1699.99 including free shipping. Their price is $300 off MSRP, and it’s the lowest price available for this model from any reseller (and... Read more
Apple Beats Microsoft at Own Game; Amazon Pri...
First quarter seasonality combined with an overall disinterested customer base led to an annual decline of 14.7% in worldwide tablet shipments during the first quarter of 2016 (1Q16). Worldwide... Read more
Tablets Had Worst Quarter Since 2012, says St...
The global tablet market began 2016 just as 2015 left off, down. Tablet shipments fell 10% to 46.5 million units during the Q1 2016, according to the new “Preliminary Global Tablet Shipments and... Read more
Clearance 13-inch MacBook Airs, Apple refurbi...
Apple recently dropped prices on certified refurbished 2015 13″ MacBook Airs with 4GB of RAM with models now available starting at $759. An Apple one-year warranty is included with each MacBook, and... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has dropped prices on Certified Refurbished 2015 12″ Retina MacBooks with models now available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping... Read more
Aleratec Releases Mac Software Upgrade for 1...
California based Aleratec Inc., designer, developer and manufacturer of Portable Device Management (PDM) charge/sync products for mobile devices and professional-grade duplicators for hard disk... Read more
Sale! Amazon offers 27-inch iMac, 13-inch 2.9...
Amazon has the 27″ 3.2GHz 5K iMac and the 13″ 3.9GHz Retina MacBook Pro on sale for $300 off MSRP, each including free shipping, for a limited time: - 27″ 3.2GHz/1TB HD 5K iMac (model MK462LL/A): $... 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
13-inch 2.7GHz/128GB Retina MacBook Pro on sa...
Take $200 off MSRP on the price of a new 13″ 2.7GHz/128GB Retina MacBook Pro (model MF839LL/A) at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1099.99 $200 off MSRP Act now if... Read more

Jobs Board

Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 48260200 Phoenix, Arizona, United States Posted: Apr. 22, 2016 Weekly Hours: 40.00 **Job Summary** As an Apple Solutions Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.