DialogHandler™ Helps Dialogs

By Dave Kelly, MacTutor Editorial Board

DialogHandler™ Handles Your Dialogs!

If you’d like to cut your programming time Extender DialogHandler™ will come to the rescue. I’m busy and my time is worth something so why should I reinvent the wheel? DialogHandler™ is different from the other programming tools that I’ve mentioned before such as Prototyper™ which generates code for you. Instead you get a set of already programmed routines which you use to write your code. DialogHandler does not create the “shell” for you so you can use your own and take advantage of over 160 routines which are very well documented. Because you are writing the code which accesses the routines, you are able to understand and organize your program in the way you want.

This month I’ve been working with DialogHandler and I can see there are some definite advantages to using it. The major advantage is that DialogHandler takes care of the nitty-gritty details of handling the items in your dialog. Both Pascal and C versions are available which conveniently provide dialog control for check boxes, push buttons, radio buttons (with multiple sets), pop-up menus, icons (including animation), pictures, all types of edit fields and more. DialogHandler comes with 100% source code so you can study the routines to learn more about programming the Macintosh. Although you have the source code, you won’t need to figure out how to modify the source code since nearly every routine has hooks to user defined procedures so you can extend the routines without having to figure out what or how to modify the source code.

The place to start is with the documentation. At first glance DialogHandler looks like another volume of Inside Macintosh. Don’t “judge a book by its cover” though because the entire manual was carefully organized to help you get the most out of it. The manual is divided into three or four major sections (in two 3-ring binders):

• Concepts and Examples: This section gives an overview of all of the routines included in DialogHandler with demo examples. I strongly recommend starting with the Concepts and Examples section first. Even if you think you already know it all, a brief skim through of this section will probably answer whatever questions you might ask when you get stuck on something. The demo examples cover any and everything you might do with the routines. There is a demo for each set of routines and one big one appropriately named “The Kitchen Sink” which implements everything all in one dialog.

Figure 1. The Kitchen Sink

As you can see from just looking at the “Kitchen Sink” dialog, push buttons, multiple sets of Radio buttons, check boxes, counters, pictures, icons, pop-up menus, multiple user defined pull down menu bars, edit string, edit integer, edit LongInt, edit real, static string, static integer, static LongInt, static real and lists. In addition, note that key equivalents may be assigned to any of the items. A few utility routines are included too for convenience.

• Reference: This section is organized alphabetically by procedure/function names with syntax and all parameters explained.

• Advanced Topics and Appendix: Hints and essential information for setting up DialogHandler with your specific compiler. One appendix gives a summary of all DialogHandler routines.

• A very extensive index to help you find whatever, every which way you can.

Since the manual is in a three ring binder you can take out the pages you use most (I like to pull out the summary section when I’m working with DialogHandler). Neil Ticktin has done a great job of making sure that the DialogHandler™ manual has the answers.

The following example is one of the simplest (useful) functions of a dialog box. The user is required to enter an integer that falls in the -100 to 100 range. If the user hits the OK button, the value entered is saved in a variable, but if he hits the Cancel button, the value is not saved. Built into this simple example is on-the-fly character filtering to maintain integer integrity; range checking with alert boxes; default item bold outline; as well as cut, copy, and paste support with context checking -- all with 6 lines of code.

I’ve set up a demo program of my own(this one is not just a demo, but usable also) which will show you a little of how the programming scheme is set up when using DialogHandler™. Since I’m using only one dialog, I don’t use an event loop, although you could have one very easily. To start off with, the dialog resource must be created. I used Prototyper™ to get the dialog to look the way I wanted it and then created the resource only. Next, the source code includes a loop similar to the following loop for each dialog:

{1}

procedure DoThatDialog
var
 dhp: DialogHandlerRecordPtr;
begin
 DHNewRecord(dhp, DialogIDNumber, UpdateUserItemNum, CancelButtonNum, 
NoSelectedItem);
 •
 •
 {Front End Calls to Describe the Dialog}
 •
 •
 if DHDialogHandler (dhp) then
 begin  {user hit the OK button instead of Cancel}
 •
 •
 {Front End Calls to Retrieve { Information from dhp }
 •
 •
 end;
 DHDeallocateRecord(dhp);
end.  {procedure DoThatDialog }

Front End calls are DialogHandler routines which set up the dialog before it is actually drawn on the screen. Other Front End calls are used to retrieve information from the dialog. The code fairly easy to follow:

Should I buy it or not? May I remind you once again that “time is money”. After investing about 2-3 hours skimming over the documentation, I was ready to build a simple dialog based application from start to finish in just a few hours. Maybe some of you can already do that, if so maybe you should write your own code. Since my time is limited I can’t take the hours and days (or even weeks) before I see my finished product. DialogHandler will certainly help you get to the finished product sooner. DialogHandler starts where Prototyper and AppMaker end; DialogHandler allows you to deal with dialog details not offered anywhere (unless you wrote your own routines). It doesn’t write the program for you, but it helps you get close to the end product quickly. Add these routines to your own shell and you’re ready to go.

Professional Extender DialogHandler requires System 6.02 or later and 1 MB of memory. Certain features (such as pop-up and pull down menus) are not supported unless your Macintosh has at least 128K ROMs. A hard disk is recommended.

Available from:

Invention Software

P. O. Box 3168

Ann Arbor, MI. 48106

313/996-8108

Price: 189.95

NOT COPY PROTECTED!!

Listing:  CapitalsMain.p

program DialogDemo;

 uses
 Memtypes, Quickdraw, OSIntf, ToolIntf, PackIntf, SANE, DialogHandlerHeader;

 const
 DLog_ID = 10000;
 DLogGotIt = 1;
 DLogDone = 2;
 DLogQUESTION = 3;
 DLogANSWER = 4;
 DLogPickUserItem = 5;
 DLogUpdateUserItem = 6;
 DLogComment = 7;

 CapitalListStrings = 1570;
 CapitalStrings = 9042;
 StateStrings = 2460;
 numberofallstates = 50;

 var
 stateindex, capitalindex: integer;
 Capital: array[1..50] of integer;
 Radiobuttonstatus: integer;
 set1: RadioButtonSetPtr;
 stcap, cities: str255;
 currentstate: str255;

 function rand (limit: integer): integer;  {returns a random number between 
1 and limit}
 var
 secs, x: longint;
 begin
 GetDateTime(secs);
 randseed := secs;
 x := abs(random);
 while x >= limit do
 begin
 x := x div 10;
 end;
 x := x + 1;
 rand := x;
 end;

 procedure Mystartproc (dp: DialogPtr; itemHit: Integer; doubleclick: 
boolean; PickHandle: Listhandle; dhp: DialogHandlerRecordPtr);
 var
 i: integer;
 Selectresult: boolean;
 itemtype, ans: integer;
 itemHandle: Handle;
 itemRect: rect;
 begin
 Stateindex := rand(numberofallstates);
 GetIndString(currentstate, StateStrings, Stateindex);
 PickHandle := DHGetPickListHandle(dhp, DLogPickUserItem);
 DHEmptyPickList(PickHandle);
 DHAddPickListStringList(PickHandle, CapitalListStrings);
 DHAddStaticString(dhp, DLogQuestion, currentState);
 GetDItem(dp, DLogQuestion, itemType, itemHandle, itemRect);
 SetIText(itemHandle, currentState);
 end;

 procedure GotIt (dp: DialogPtr; itemHit: Integer; dhp: DialogHandlerRecordPtr);
 var
 PickHandle: Listhandle;
 Selectresult: boolean;
 itemtype, ans: integer;
 itemHandle: Handle;
 itemRect: rect;
 begin
 PickHandle := DHGetPickListHandle(dhp, DLogPickUserItem);
 Selectresult := DHIsPickListItemSelected(PickHandle, capital[stateindex] 
- 1);
 if Selectresult then
 begin  {correct answer!}
 GetDItem(dp, DLogComment, itemType, itemHandle, itemRect);
 SetIText(itemHandle, ‘Last Selection was correct!’);
 MyStartProc(dp, itemHit, false, PickHandle, dhp);
 end
 else
 begin  {wrong answer}
 GetDItem(dp, DLogComment, itemType, itemHandle, itemRect);
 SetIText(itemHandle, ‘Last Selection was wrong!’);
 end;

 end;

 procedure DoThatDialog;
 var
 dhp: DialogHandlerRecordPtr;
 i, offset: integer;
 begin
 DHNewRecord(dhp, DLog_ID, DefaultItem, DLogUpdateUserItem, NoCancelItem, 
NoSelectedItem);
 DHShowArrowCursor;
 DHAddPushButton(dhp, DLogDone, Exit);
 DHAdvAddPushButton(dhp, DLogGotIt, NoExit, DHNoKeyEquiv, @GotIt);
 DHAddPickList(dhp, DLogPickUserItem, @MyStartProc);
 for i := 1 to 50 do
 begin
 GetIndString(stcap, CapitalStrings, i);
 offset := 0;
 repeat
 begin
 offset := offset + 1;
 GetIndString(cities, CapitalListStrings, offset);
 end;
 until stcap = cities;
 capital[i] := offset;
 end;
 Stateindex := rand(numberofallstates);
 GetIndString(currentstate, StateStrings, Stateindex);
 DHAddStaticString(dhp, DLogQuestion, currentState);
 DHSetCentering(dhp, True, True, SaveCenteringOff);
 if DHDialogHandler(dhp) then
 begin {user hit the OK}
                  {End the program}
 end;
 DHDeallocateRecord(dhp);
 end;

begin
 DoThatDialog;
end.

Listing:  Capitals.r

resource ‘DLOG’ (10000, “Professor Mac’s Capital Game”) {
 {42, 2, 300, 370},
 documentProc,
 invisible,
 noGoAway,
 0x1,
 10000,
 “Professor Mac’s Capital Game”
};

resource ‘DITL’ (10000, “Professor Mac’s Capital Game”) {
 { /* array DITLarray: 8 elements */
 /* [1] */
 {123, 203, 143, 283},
 Button {
 enabled,
 “I got it! “
 },
 /* [2] */
 {161, 203, 181, 283},
 Button {
 enabled,
 “I’m Done”
 },
 /* [3] */
 {31, 162, 53, 322},
 StaticText {
 disabled,
 “”
 },
 /* [4] */
 {31, 31, 52, 163},
 StaticText {
 disabled,
 “Find the Capital of:”
 },
 /* [5] */
 {55, 31, 201, 183},
 UserItem {
 enabled
 },
 /* [6] */
 {0, 0, 0, 0},
 UserItem {
 enabled
 },
 /* [7] */
 {210, 32, 233, 344},
 StaticText {
 enabled,
 “”
 },
 /* [8] */
 {76, 224, 108, 256},
 Icon {
 enabled,
 257
 }
 }
};

resource ‘STR#’ (2460, “States”) {
 { /* array StringArray: 50 elements */
 /* [1] */
 “Alabama”,
 /* [2] */
 “Alaska”,
 /* [3] */
 “Arizona”,
 /* [4] */
 “Arkansas”,
 /* [5] */
 “California”,
 /* [6] */
 “Colorado”,
 /* [7] */
 “Connecticut”,
 /* [8] */
 “Delaware”,
 /* [9] */
 “Florida”,
 /* [10] */
 “Georgia”,
 /* [11] */
 “Hawaii”,
 /* [12] */
 “Idaho”,
 /* [13] */
 “Ilinois”,
 /* [14] */
 “Indiana”,
 /* [15] */
 “Iowa”,
 /* [16] */
 “Kansas”,
 /* [17] */
 “Kentucky”,
 /* [18] */
 “Louisiana”,
 /* [19] */
 “Maine”,
 /* [20] */
 “Maryland”,
 /* [21] */
 “Massachusetts”,
 /* [22] */
 “Michigan”,
 /* [23] */
 “Minnesota”,
 /* [24] */
 “Mississippi”,
 /* [25] */
 “Missouri”,
 /* [26] */
 “Montana”,
 /* [27] */
 “Nebraska”,
 /* [28] */
 “Nevada”,
 /* [29] */
 “New Hampshire”,
 /* [30] */
 “New Jersey”,
 /* [31] */
 “New Mexico”,
 /* [32] */
 “New York”,
 /* [33] */
 “North Carolina”,
 /* [34] */
 “North Dakota”,
 /* [35] */
 “Ohio”,
 /* [36] */
 “Oklahoma”,
 /* [37] */
 “Oregon”,
 /* [38] */
 “Pennsylvania”,
 /* [39] */
 “Rhode Island”,
 /* [40] */
 “South Carolina”,
 /* [41] */
 “South Dakota”,
 /* [42] */
 “Tennessee”,
 /* [43] */
 “Texas”,
 /* [44] */
 “Utah”,
 /* [45] */
 “Vermont”,
 /* [46] */
 “Virginia”,
 /* [47] */
 “Washington”,
 /* [48] */
 “West Virginia”,
 /* [49] */
 “Wisconsin”,
 /* [50] */
 “Wyoming”
 }
};

resource ‘STR#’ (9042, “Capitals”) {
 { /* array StringArray: 50 elements */
 /* [1] */
 “Montgomery”,
 /* [2] */
 “Juneau”,
 /* [3] */
 “Phoenix”,
 /* [4] */
 “Little Rock”,
 /* [5] */
 “Sacramento”,
 /* [6] */
 “Denver”,
 /* [7] */
 “Hartford”,
 /* [8] */
 “Dover”,
 /* [9] */
 “Tallahassee”,
 /* [10] */
 “Atlanta”,
 /* [11] */
 “Honolulu”,
 /* [12] */
 “Boise”,
 /* [13] */
 “Springfield”,
 /* [14] */
 “Indianapolis”,
 /* [15] */
 “Des Moines”,
 /* [16] */
 “Topeka”,
 /* [17] */
 “Frankfort”,
 /* [18] */
 “Baton Rouge”,
 /* [19] */
 “Augusta”,
 /* [20] */
 “Annapolis”,
 /* [21] */
 “Boston”,
 /* [22] */
 “Lansing”,
 /* [23] */
 “St. Paul”,
 /* [24] */
 “Jackson”,
 /* [25] */
 “Jefferson City”,
 /* [26] */
 “Helena”,
 /* [27] */
 “Lincoln”,
 /* [28] */
 “Carson City”,
 /* [29] */
 “Concord”,
 /* [30] */
 “Trenton”,
 /* [31] */
 “Santa Fe”,
 /* [32] */
 “Albany”,
 /* [33] */
 “Raleigh”,
 /* [34] */
 “Bismarck”,
 /* [35] */
 “Columbus”,
 /* [36] */
 “Oklahoma City”,
 /* [37] */
 “Salem”,
 /* [38] */
 “Harrisburg”,
 /* [39] */
 “Providence”,
 /* [40] */
 “Columbia”,
 /* [41] */
 “Pierre”,
 /* [42] */
 “Nashville”,
 /* [43] */
 “Austin”,
 /* [44] */
 “Salt Lake City”,
 /* [45] */
 “Montpelier”,
 /* [46] */
 “Richmond”,
 /* [47] */
 “Olympia”,
 /* [48] */
 “Charleston”,
 /* [49] */
 “Madison”,
 /* [50] */
 “Cheyenne”
 }
};

resource ‘STR#’ (1570, “CapitalAnswers”) {
 { /* array StringArray: 107 elements */
 /* [1] */
 “Albany”,
 /* [2] */
 “Albuquerque”,
 /* [3] */
 “Anchorage”,
 /* [4] */
 “Annapolis”,
 /* [5] */
 “Atlanta”,
 /* [6] */
 “Augusta”,
 /* [7] */
 “Austin”,
 /* [8] */
 “Baltimore”,
 /* [9] */
 “Baton Rouge”,
 /* [10] */
 “Billings”,
 /* [11] */
 “Bismarck”,
 /* [12] */
 “Boise”,
 /* [13] */
 “Boulder”,
 /* [14] */
 “Boston”,
 /* [15] */
 “Bowling Green”,
 /* [16] */
 “Buffalo”,
 /* [17] */
 “Burlington”,
 /* [18] */
 “Carson City”,
 /* [19] */
 “Cedar City”,
 /* [20] */
 “Charleston”,
 /* [21] */
 “Chattanooga”,
 /* [22] */
 “Cheyenne”,
 /* [23] */
 “Chicago”,
 /* [24] */
 “Cleveland”,
 /* [25] */
 “Colorado Springs”,
 /* [26] */
 “Columbia”,
 /* [27] */
 “Columbus”,
 /* [28] */
 “Concord”,
 /* [29] */
 “Dallas”,
 /* [30] */
 “Denver”,
 /* [31] */
 “Des Moines”,
 /* [32] */
 “Detroit”,
 /* [33] */
 “Dover”,
 /* [34] */
 “Frankfort”,
 /* [35] */
 “Harrisburg”,
 /* [36] */
 “Hartford”,
 /* [37] */
 “Helena”,
 /* [38] */
 “Honolulu”,
 /* [39] */
 “Houston”,
 /* [40] */
 “Huntington”,
 /* [41] */
 “Indianapolis”,
 /* [42] */
 “Jackson”,
 /* [43] */
 “Jefferson City”,
 /* [44] */
 “Juneau”,
 /* [45] */
 “Kansas City”,
 /* [46] */
 “Lansing”,
 /* [47] */
 “Las Vegas”,
 /* [48] */
 “Lexington”,
 /* [49] */
 “Lincoln”,
 /* [50] */
 “Little Rock”,
 /* [51] */
 “Louisville”,
 /* [52] */
 “Los Angeles”,
 /* [53] */
 “Madison”,
 /* [54] */
 “Manchester”,
 /* [55] */
 “Memphis”,
 /* [56] */
 “Miami”,
 /* [57] */
 “Milwaukee”,
 /* [58] */
 “Minneapolis”,
 /* [59] */
 “Montgomery”,
 /* [60] */
 “Montpelier”,
 /* [61] */
 “Nashville”,
 /* [62] */
 “Nauvoo”,
 /* [63] */
 “New Orleans”,
 /* [64] */
 “New York City”,
 /* [65] */
 “Newark”,
 /* [66] */
 “Norfolk”,
 /* [67] */
 “Oakland”,
 /* [68] */
 “Ogden”,
 /* [69] */
 “Oklahoma City”,
 /* [70] */
 “Olympia”,
 /* [71] */
 “Omaha”,
 /* [72] */
 “Orlando”,
 /* [73] */
 “Philadelphia”,
 /* [74] */
 “Phoenix”,
 /* [75] */
 “Pierre”,
 /* [76] */
 “Pittsburgh”,
 /* [77] */
 “Phoenix”,
 /* [78] */
 “Pocatello”,
 /* [79] */
 “Portland”,
 /* [80] */
 “Providence”,
 /* [81] */
 “Raleigh”,
 /* [82] */
 “Rapid City”,
 /* [83] */
 “Richmond”,
 /* [84] */
 “Rochester”,
 /* [85] */
 “Sacramento”,
 /* [86] */
 “Salem”,
 /* [87] */
 “Salt Lake City”,
 /* [88] */
 “San Antonio”,
 /* [89] */
 “San Diego”,
 /* [90] */
 “San Francisco”,
 /* [91] */
 “Santa Barbara”,
 /* [92] */
 “Santa Fe”,
 /* [93] */
 “Seattle”,
 /* [94] */
 “Shreveport”,
 /* [95] */
 “Springfield”,
 /* [96] */
 “Souix Falls”,
 /* [97] */
 “St. Louis”,
 /* [98] */
 “St. Paul”,
 /* [99] */
 “Tallahassee”,
 /* [100] */
 “Topeka”,
 /* [101] */
 “Trenton”,
 /* [102] */
 “Tucson”,
 /* [103] */
 “Vancouver”,
 /* [104] */
 “Washington”,
 /* [105] */
 “Wichita”,
 /* [106] */
 “Wilmington”,
 /* [107] */
 “Yuma”
 }
};

data ‘PROF’ (0) {
 $”1C A9 31 39 38 39 20 4D 61 63 54 75 74 6F 72 0D”    /* .©1989 MacTutor¬ 
*/
 $”62 79 20 44 61 76 65 20 4B 65 6C 6C 79 00"          /* by Dave Kelly. 
*/
};

resource ‘ICON’ (257, “Professor Mac”) {
 $”00 00 00 00 00 1C 00 00 00 3E 00 00 00 7F 80 00"
 $”00 FF E0 00 01 FF F8 00 03 FF FC 00 07 FB FC 00"
 $”07 FE F8 00 03 FF B0 00 01 7F F8 00 02 1F F4 00"
 $”02 E7 92 00 02 D1 17 00 02 00 12 00 02 00 17 00"
 $”02 80 92 00 02 FF 90 00 02 77 17 6C 01 00 22 54"
 $”00 80 42 54 00 7F 80 00 00 40 80 00 00 7F 80 00"
 $”01 80 60 00 06 00 18 00 08 61 84 00 13 0C 32 00"
 $”10 00 02 00 1F FF FE”
};

resource ‘ICN#’ (128) {
 { /* array: 2 elements */
 /* [1] */
 $”00 00 00 00 00 00 00 00 00 00 00 00 00 07 00 00"
 $”00 0F 80 00 00 1F E0 00 00 3F F8 00 00 7F FE 00"
 $”00 FF FF 00 01 FE FF 00 01 FF BE 00 00 FF EC 00"
 $”00 5F FE 00 00 87 FD 00 00 B9 E4 80 00 B4 45 C0"
 $”00 80 04 80 00 80 05 C0 00 A0 24 80 00 BF E4 00"
 $”00 9D C5 DB 00 40 08 95 00 20 10 95 00 1F E0 00"
 $”00 10 20 00 00 1F E0 00 00 60 18 00 01 80 06 00"
 $”02 18 61 00 04 C3 0C 80 04 00 00 80 07 FF FF 80",
 /* [2] */
 $”00 00 00 00 00 00 00 00 00 00 00 00 00 07 00 00"
 $”00 0F 80 00 00 1F E0 00 00 3F F8 00 00 7F FE 00"
 $”00 FF FF 00 01 FF FF 00 01 FF FE 00 00 FF FC 00"
 $”00 7F FE 00 00 FF FD 00 00 FF FC 80 00 FF FD C0"
 $”00 FF FC 80 00 FF FD C0 00 FF FC 80 00 FF FC 00"
 $”00 FF FD DB 00 7F F8 95 00 3F F0 95 00 1F E0 00"
 $”00 1F E0 00 00 1F E0 00 00 7F F8 00 01 FF FE 00"
 $”03 FF FF 00 07 FF FF 80 07 FF FF 80 07 FF FF 80"
 }
};

resource ‘ICN#’ (129) {
 { /* array: 2 elements */
 /* [1] */
 $”00 00 00 00 7F FF FF 80 40 3F FD 40 40 7F FD 20"
 $”40 FF FD 10 41 FF FD 08 43 FF FD FC 47 FF FC 04"
 $”4F FE FF FC 5F FD 01 F4 4F FE FE 64 47 FF FF C4"
 $”41 FF FF A4 42 3F FF 94 44 0F FE 94 44 63 FC BC”
 $”44 F0 F8 94 44 C8 30 AC 44 00 00 94 45 18 C4 AC”
 $”45 7D F4 94 45 FF FC AC 44 FD F8 94 44 38 E0 AC”
 $”44 00 00 84 43 FF FF 04 47 FF FF 84 4C 00 00 C4"
 $”51 8C CC 24 60 00 00 14 7F FF FF FC 7F FF FF FC”,
 /* [2] */
 $”00 00 00 00 7F FF FF 80 7F FF FF C0 7F FF FF E0"
 $”7F FF FF F0 7F FF FF F8 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 $”7F FF FF FC 7F FF FF FC 7F FF FF FC 7F FF FF FC”
 }
};

resource ‘FREF’ (128) {
 ‘APPL’,
 0,
 “”
};

resource ‘FREF’ (129) {
 ‘TEXT’,
 1,
 “”
};

resource ‘BNDL’ (128) {
 ‘PROF’,
 0,
 { /* array TypeArray: 2 elements */
 /* [1] */
 ‘ICN#’,
 { /* array IDArray: 2 elements */
 /* [1] */
 0, 128,
 /* [2] */
 1, 129
 },
 /* [2] */
 ‘FREF’,
 { /* array IDArray: 2 elements */
 /* [1] */
 0, 128,
 /* [2] */
 1, 129
 }
 }
};