Apr 98 - Getting Started
Volume Number: 14
Issue Number: 4
Column Tag: Getting Started
Having a Dialog with Your Mac
by Dave Mark
Programming the Dialog Manager
In last month's column, we explored the inner workings of the Menu Manager. This
month, we'll build on that experience and create a program with menus, windows, and,
for the first time, dialogs and alerts. This program is the biggest one we've tackled so
far, so this months column is a bit longer than usual.
Creating the Dialogger Resources
We'll start off just as we did in last month's column, by creating our MBAR and MENU
resources. Create a folder inside your Development folder named "Dialogger Folder.
Next, launch ResEdit and create a new file called Dialogger.rsrc inside this new folder.
Now select Create New Resource from the Resource menu and create a new MBAR
resource according to the specifications in Figure 1. As you can see, our program
will feature three different menus.
Figure 1. Specifications for Dialogger's MBAR resource.
Close the MBAR and MBAR picker windows and again select Create New Resource from
the Resource menu. Create a MENU resource according to the specifications in Figure
2. This MENU represents the Apple menu. Be sure that the MENU's resource id is 128.
Figure 2. Specifications for the Apple MENU resource.
Now create another MENU resource according to the specifications shown in Figure
3. This MENU represents the File menu. Be sure the MENU's resource id is set to 129.
Figure 3. Specifications for the File MENU resource.
Now create one final MENU resource according to the specifications shown in Figure
4. This MENU represents the Edit menu. Be sure this MENU's resource id is set to
130.
Figure 4. Specifications for the Edit MENU resource.
OK. Close up your MENU and MENU picker windows. This next part might be a little
tricky. You'll need three PICT images, one of a dog, one of an elephant, and one of a
squirrel. If you don't have any of these handy, drop into your favorite graphics
program and do the best you can. If you're really stuck, just create pictures with the
words Afghan, Elephant, and Squirrel in them. Paste all three pictures into your
scrapbook.
Back in ResEdit, Paste the pictures into three PICT resources. Use Figure 5 as your
guide. Be sure your afghan is PICT 128, your elephant is PICT 129, and that your
squirrel is PICT 130.
Figure 5. Three PICT resources. Note which resource id goes with which PICT.
Actually, you can use any PICT images that strike your fancy. Once you understand
what this program does and how it works, feel free to customize it to your own desires.
Close the PICT picker window. Once again, select Create New Resource from the
Resource menu. This time, create a DLOG resource. A miniature version of your
desktop will appear with a window somewhere in the middle. Depending on the size of
your monitor, your DLOG window may appear somewhat scaled. When the DLOG editor
appears, customize it according to the specifications in Figure 6.
Figure 6. Specifications for the DLOG resource.
Be sure that you click the dialog window type (8th from the left) at the top of the
editing window. Also, be sure you uncheck the Initially visible and Close box check
boxes on the right side of the window. This resource controls the appearance of a dialog
box's window. Now we'll create a resource that defines the items that appear in this
DLOG.
Double-click the DLOG window (not the editing window, but the window that appears in
the middle of the editing window, on the mini-desktop) and a DITL editing window will
appear. At the same time, a DITL item palette will appear (Figure 7). This palette
contains a list of all the items you can add to your dialog.
Figure 7. The DITL item palette.
When you start constructing a DITL (Dialog ITem List), you always start with the OK
and Cancel buttons. The OK button is always item number one, and the Cancel button (if
it exists) is always item number two. As you'll learn, these item numbers have special
significance to the Dialog Manager. Click the Button palette, dragging to the left, on to
your DITL window. The outline of a button will appear (Figure 8).
Figure 8. Dragging a button from the palette window.
When you release the mouse button, a new button item will appear. Double click this
button item and a specifications window will appear. Fill it in according to the specs
shown in Figure 9. Notice that the Enabled check box is checked. This tells the Dialog
Manager to respond to this item when it is clicked on in a dialog box. If the item were
not enabled, clicks in it would be ignored.
Figure 9. Specifications for DITL item #1.
Close the spec window and drag a second button from the palette. Double-click it and
enter the specs shown in Figure 10. Close the specs window.
Figure 10. Specifications for DITL item #2.
This time, drag a Radio Button fromthe palette. Double-click it and make it reflect the
specs shown in Figure 11. Close the specs window.
Figure 11. Specifications for DITL item #3.
Drag a second Radio Button from the palette and make it reflect the specs shown in
Figure 12.
Figure 12. Specifications for DITL item #4.
Drag a third Radio Button from the palette and make it reflect the specs shown in
Figure 13.
Figure 13. Specifications for DITL item #5.
Next, drag a Static Text item from the palette and make it reflect the specs in Figure
14. Notice that the Enabled check box is unchecked. Normally, user clicks in static
text are ignored.
Figure 14. Specifications for DITL item #6.
Next, drag a Check Box item from the palette and make it reflect the specs in Figure
15.
Figure 15. Specifications for DITL item #7.
Finally, drag a User Item from the palette and make it reflect the specs in Figure 16.
As was the case with Static Text, notice that the Enabled check box is unchecked. A User
Item just acts as a marking rectangle. We'll use it as a guide for drawing a picture,
later in the program. There may be times when you want your User Items enabled. For
now leave it as is.
Figure 16. Specifications for DITL item #8.
When you close your last item spec window, your DITL editing window should look like
the one shown in Figure 17. If it doesn't, go back and check out your specs. If you
need to make changes, you can use the tools in the DITL menu, such as Show Item
Numbers, Set Item Number..., and Renumber Items....
Figure 17. The completed DITL resource.
OK, we're almost done. Close the DITL and DLOG windows till you're back down to your
main window. You might want to save at this point. I'll wait... Select Create New
Resource from the Resource menu and create an ALRT resource. The ALRT editor looks
just like the DLOG editor. It should. Alerts are basically simplified dialogs, easier to
use and easier to build. (Top: 40, Left: 40, Bottom: 145, Right: 350)
Select Get Resource Info from the Resource menu and change the ALRT's resource id to
129. Next, close the Info window and change the DITL ID: field in the ALRT window to
129. We have to create a DITL for the items in the alert and, since we've already got a
DITL 128, we'll use 129 for the alert.
In general, it's a good idea to keep the ALRT and DLOG resource ids in sync with their
respective DITL resource ids. Our DLOG 128 goes with DITL 128 and ALRT 129 goes
with DITL 129.
Double-click the ALRT window inside the mini-desktop. A new DITL resource will
appear. You'll add two items to the DITL. First, create a Button according to the specs
in Figure 18.
Figure 18. Specifications for the alert's OK button.
Next, create a Static Text item item according to the specs in Figure 19. Be sure the
Enabled check box is unchecked.
Figure 19. Specifications for DITL item #2.
Whew! That's it. Quit ResEdit, being sure to save your changes. Let's get to the project.
Creating the Dialogger Project
Launch CodeWarrior and create a new project based on the MacOS:C/C++:Basic Toolbox
68k stationary. Turn off the Create Folder check box. Name the project Dialogger.mcp
and place it in your Dialogger folder. Remove SillyBalls.c and SillyBalls.rsrc from the
project; we will not be using these files. From the Finder, drag and drop your
Dialogger.rsrc file into the project window. You also can remove the ANSI Libraries
group from the project, because we won't need them, either.
Select New from the File menu to create a new window. Save it under the name
Dialogger.c, Select Add Window from the Project menu to add Dialogger.c to the
project. Your project window should look something like Figure 20.
Figure 20. Dialogger project window.
Rather than print the code here twice, we'll go straight to the walk-through. You can
type in the code as we discuss it below and you will end up with the complete program,
or you can save your fingers some effort and get the complete project from MacTech's
ftp site ftp://ftp.mactech.com/src/.
Walking Through the Source Code
Much of the Dialogger source code will look familiar to you from earlier programs. I'll
keep the chatter to a minimum. You've seen some of these constants before. The rest I'll
explain as we get to them. One convention you should be aware of is the 'i' convention.
Just as we did with menu items, constants that reflect a dialog item start with the
letter 'i'.
#include
#include
#include
#include
#include
#define kBaseResID 128
#define kAboutALRTid 129
#define kDialogResID 128
#define kVisible true
#define kMoveToFront (WindowPtr)-1L
#define kNoGoAway false
#define kSleep 7L
#define kFirstRadio 3
#define kOn 1
#define kOff 0
Each time you add an item to a dialog item list, the item is given a unique number. The