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

How to get more cars in CSR Racing 2
NaturalMotion and Zynga brought a lot of real life cars to the table for CSR Racing 2. From souped up everyday rides made by Nissan and Hyundai to supercars produced by the likes of McLaren and Pagani, there really is something for everyone. [... | Read more »
Crypt of the NecroDancer Pocket Edition...
Crypt of the NecroDancer Pocket Edition 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Crypt of the NecroDancer is an award winning hardcore roguelike rhythm game. Move to the music and... | Read more »
Gear-grinding puzzle title Inner Circle...
If you saw our post earlier this month announcing the imminent release of ZPlay’s new creation, Inner Circle, you’ll be happy to know that it’s now available on the App Store. Established in 2010, developer and publisher ZPlay have taken the... | Read more »
CSR Racing 2: Your guide to what's...
CSR Racing 2, or CSR2, as it likes to call itself, has finally arrived. The follow-up to the immensely popular drag racing game CSR Racing is the first release from NaturalMotion since the studio's acquisition by Zynga in early 2014. [Read more] | Read more »
Nanuleu (Games)
Nanuleu 1.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1 (iTunes) Description: Nanuleu is a strategy game where you take control of ancient magical trees that protect the land from an invading dark force. A... | Read more »
The Slaughter: Act One (Games)
The Slaughter: Act One 1.0.323 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.323 (iTunes) Description: “The game mixes realism and surrealism to create a story that can cause just as much laughter as fear. A-” -... | Read more »
NEO TURF MASTERS (Games)
NEO TURF MASTERS 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: NEOGEO’s legendary golf game is back, in a brand-new mobile version with touch controls! NEO TURF MASTERS (also known as “BIG... | Read more »
How to send money to a friend with the F...
Facebook is already a lot of things to a lot of people. It's a social network, sure, but also a tool for catologing memories, chatting with friends, and much more. [Read more] | Read more »
Branch out into the Chinese market with...
Created a game that you’re super enthused about, only to find yourself struggling to get it the exposure that you believe it duly deserves? With the time, energy and money that goes into development, it’s only right that games should be given the... | Read more »
Pocket Arcade Story (Games)
Pocket Arcade Story 1.00 Device: iOS Universal Category: Games Price: $4.99, Version: 1.00 (iTunes) Description: Here comes a new challenger: it's the arcade simulation game you've been waiting for! Build your very own gaming... | Read more »

Price Scanner via MacPrices.net

New App Reminds Us to Put Down Our Phones and...
Mode, a new smartphone app that makes us more mindful of how we use our devices, debuts in the app stores today. The Mode app tracks time spent in different modes of day-to-day life without... Read more
ZuumSpeed Personalized Speedometer + HUD For...
RMKapps has announced the release and immediate availability of ZuumSpeed 1.0, its personalized speedometer plus heads up display for iOS devices. ZuumSpeed gives users over 18 custom fonts available... Read more
Apple refurbished clearance 15-inch Retina Ma...
Apple has Certified Refurbished 2014 15″ 2.2GHz Retina MacBook Pros available for $1609, $390 off original MSRP. Apple’s one-year warranty is included, and shipping is free. They have refurbished 15... Read more
9-inch 128GB Silver iPad Pro on sale for $50...
B&H Photo has the 9.7″ 128GB Silver Apple iPad Pro on sale for $699 including free shipping plus NY tax only. Their price is $50 off MSRP. Read more
Why Use Indie Opera And Vivaldi Instead Of Sa...
For many years my web browser workhorses were various permutations and spinoffs of the Netscape/Mozilla/Firefox Open Source platform, and the Norwegian indie browser Opera, which I took a shine to... Read more
Western Digital Launches Worlds Fastest 256GB...
At the Mobile World Congress in Shanghai Western Digital Corporation this week introduced a new suite of 256 gigabyte (GB) microSD cards, which includes the new 256GB SanDisk Extreme microSDXC UHS-I... Read more
KeyCue 8.1 Integrates With Typinator To Displ...
Ergonis Software has released KeyCue 8.1, a new version of the company’s keyboard shortcut cheat sheet. KeyCue 8 introduced a new way to define a wide variety of triggers, which can be used to... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more
21-inch 2.8GHz iMac on sale for $1199, save $...
Amazon has the 21″ 2.8GHz iMac (model #MK442LL/A) on sale for $1199.99 including free shipping. Their price is $100 off MSRP, and it’s the lowest price available for this model. Read more
13-inch 2.5GHz MacBook Pro (Apple refurbished...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more

Jobs Board

*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* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Retail - Multiple Positions, Willow...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.