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

Latest Forum Discussions

See All

Pack a magnifying glass and practice you...
Somehow it has already been a year since Torchlight: Infinite launched, and XD Games is celebrating by blending in what sounds like a truly fantastic new update. Fans of Cthulhu rejoice, as Whispering Mist brings some horror elements, and tests... | Read more »
Summon your guild and prepare for war in...
Netmarble is making some pretty big moves with their latest update for Seven Knights Idle Adventure, with a bunch of interesting additions. Two new heroes enter the battle, there are events and bosses abound, and perhaps most interesting, a huge... | Read more »
Make the passage of time your plaything...
While some of us are still waiting for a chance to get our hands on Ash Prime - yes, don’t remind me I could currently buy him this month I’m barely hanging on - Digital Extremes has announced its next anticipated Prime Form for Warframe. Starting... | Read more »
If you can find it and fit through the d...
The holy trinity of amazing company names have come together, to release their equally amazing and adorable mobile game, Hamster Inn. Published by HyperBeard Games, and co-developed by Mum Not Proud and Little Sasquatch Studios, it's time to... | Read more »
Amikin Survival opens for pre-orders on...
Join me on the wonderful trip down the inspiration rabbit hole; much as Palworld seemingly “borrowed” many aspects from the hit Pokemon franchise, it is time for the heavily armed animal survival to also spawn some illegitimate children as Helio... | Read more »
PUBG Mobile teams up with global phenome...
Since launching in 2019, SpyxFamily has exploded to damn near catastrophic popularity, so it was only a matter of time before a mobile game snapped up a collaboration. Enter PUBG Mobile. Until May 12th, players will be able to collect a host of... | Read more »
Embark into the frozen tundra of certain...
Chucklefish, developers of hit action-adventure sandbox game Starbound and owner of one of the cutest logos in gaming, has released their roguelike deck-builder Wildfrost. Created alongside developers Gaziter and Deadpan Games, Wildfrost will... | Read more »
MoreFun Studios has announced Season 4,...
Tension has escalated in the ever-volatile world of Arena Breakout, as your old pal Randall Fisher and bosses Fred and Perrero continue to lob insults and explosives at each other, bringing us to a new phase of warfare. Season 4, Into The Fog of... | Read more »
Top Mobile Game Discounts
Every day, we pick out a curated list of the best mobile discounts on the App Store and post them here. This list won't be comprehensive, but it every game on it is recommended. Feel free to check out the coverage we did on them in the links below... | Read more »
Marvel Future Fight celebrates nine year...
Announced alongside an advertising image I can only assume was aimed squarely at myself with the prominent Deadpool and Odin featured on it, Netmarble has revealed their celebrations for the 9th anniversary of Marvel Future Fight. The Countdown... | Read more »

Price Scanner via MacPrices.net

Every model of Apple’s 13-inch M3 MacBook Air...
Best Buy has Apple 13″ MacBook Airs with M3 CPUs in stock and on sale today for $100 off MSRP. Prices start at $999. Their prices are the lowest currently available for new 13″ M3 MacBook Airs among... Read more
Sunday Sale: Apple iPad Magic Keyboards for 1...
Walmart has Apple Magic Keyboards for 12.9″ iPad Pros, in Black, on sale for $150 off MSRP on their online store. Sale price for online orders only, in-store price may vary. Order online and choose... Read more
Apple Watch Ultra 2 now available at Apple fo...
Apple has, for the first time, begun offering Certified Refurbished Apple Watch Ultra 2 models in their online store for $679, or $120 off MSRP. Each Watch includes Apple’s standard one-year warranty... Read more
AT&T has the iPhone 14 on sale for only $...
AT&T has the 128GB Apple iPhone 14 available for only $5.99 per month for new and existing customers when you activate unlimited service and use AT&T’s 36 month installment plan. The fine... Read more
Amazon is offering a $100 discount on every M...
Amazon is offering a $100 instant discount on each configuration of Apple’s new 13″ M3 MacBook Air, in Midnight, this weekend. These are the lowest prices currently available for new 13″ M3 MacBook... Read more
You can save $300-$480 on a 14-inch M3 Pro/Ma...
Apple has 14″ M3 Pro and M3 Max MacBook Pros in stock today and available, Certified Refurbished, starting at $1699 and ranging up to $480 off MSRP. Each model features a new outer case, shipping is... Read more
24-inch M1 iMacs available at Apple starting...
Apple has clearance M1 iMacs available in their Certified Refurbished store starting at $1049 and ranging up to $300 off original MSRP. Each iMac is in like-new condition and comes with Apple’s... Read more
Walmart continues to offer $699 13-inch M1 Ma...
Walmart continues to offer new Apple 13″ M1 MacBook Airs (8GB RAM, 256GB SSD) online for $699, $300 off original MSRP, in Space Gray, Silver, and Gold colors. These are new MacBook for sale by... Read more
B&H has 13-inch M2 MacBook Airs with 16GB...
B&H Photo has 13″ MacBook Airs with M2 CPUs, 16GB of memory, and 256GB of storage in stock and on sale for $1099, $100 off Apple’s MSRP for this configuration. Free 1-2 day delivery is available... Read more
14-inch M3 MacBook Pro with 16GB of RAM avail...
Apple has the 14″ M3 MacBook Pro with 16GB of RAM and 1TB of storage, Certified Refurbished, available for $300 off MSRP. Each MacBook Pro features a new outer case, shipping is free, and an Apple 1-... Read more

Jobs Board

*Apple* Systems Administrator - JAMF - Activ...
…**Public Trust/Other Required:** None **Job Family:** Systems Administration **Skills:** Apple Platforms,Computer Servers,Jamf Pro **Experience:** 3 + years of Read more
IT Systems Engineer ( *Apple* Platforms) - S...
IT Systems Engineer ( Apple Platforms) at SpaceX Hawthorne, CA SpaceX was founded under the belief that a future where humanity is out exploring the stars is Read more
Nurse Anesthetist - *Apple* Hill Surgery Ce...
Nurse Anesthetist - Apple Hill Surgery Center Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Now Read more
Housekeeper, *Apple* Valley Village - Cassi...
Apple Valley Village Health Care Center, a senior care campus, is hiring a Part-Time Housekeeper to join our team! We will train you for this position! In this role, Read more
Sublease Associate Optometrist- *Apple* Val...
Sublease Associate Optometrist- Apple Valley, CA- Target Optical Date: Apr 20, 2024 Brand: Target Optical Location: Apple Valley, CA, US, 92307 **Requisition Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.