Related Info: Dialog Manager Window Manager Event Manager

Dialogger Part II, The Code

Walking through a Dialogger

By Dave Mark, MacTech Magazine Regular Contributing Author

Last month’s column was so long that we never got a chance to walk through the source code. If you’re just entering the picture, pick up a copy of last month’s MacTutor ... er ... MacTech and read through the Getting Started column. The column describes the resources and source code that make up Dialogger, a program that demonstrates the basics of working with the Dialog Manager, an important part of the Macintosh Toolbox.

The Dialog Manager

The Dialog Manager gives you all the routines and data structures you’ll need to implement a fully functional dialog box, like the one shown in Figure 1.

Figure 1. Dialogger’s Settings... dialog box.

Dialog boxes consist of a window and a list of dialog items. Each dialog item has an associated Rect, specified in the dialog window’s local coordinates, which determines where the item appears within the window. Each item is chosen from the list shown in Figure 2. You should recognize this as the DITL item palette used in last month’s column to create the DITL resource that described the items used in the Dialogger Settings... dialog.

Figure 2. The DITL item palette.

The Dialogger DITL contained buttons, a check box, radio buttons, static text, and a user item. I’ll explain those as we encounter them in the source code. The remaining items are controls, edit text, icons, and pictures. A control is an item that can take on a limited range of values. The classic example of a control in a dialog is the scroll bar, which changes value as you scroll through a list. We’ll deal with scroll bars in a later column.

An edit text item allows you to display text that the user may edit. The Dialog Manager handles all the text editing chores for you. Pretty much all you have to do is specify the default text in the edit text item, then retrieve and reset the text as you choose.

Icons and pictures display ICON and PICT resources in the rectangle you specify. These are pretty straight-forward. Once you finish this column, go read the Dialog Manager section in Inside Macintosh, Volume I. With this example in hand, you should be able to breeze through it.

The Dialogger 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.

/* 1 */

#define kBaseResID 128
#define kAboutALRTid 129
#define kDialogResID 128

#define kVisible true
#define kMoveToFront (WindowPtr)-1L
#define kNoGoAwayfalse
#define kSleep   60L

#define kFirstRadio3

#define kOn 1
#define kOff0

Each time you add an item to a dialog item list, the item is given a unique number. The OK button always gets number 1 and the Cancel button always gets number 2. ResEdit’s DITL menu (which appears when you edit a DITL) allows you to renumber the items in a DITL, as well as turn the display of item numbers on and off. In general, it’s a good idea to write down (or print out) each of your DITL item id’s once you finish your ResEdit session and you start writing your code. I usually create the item #defines for my MENU and DITL resources right away so I won’t forget them.

/* 2 */

#define iAfghan  3
#define iElephant4
#define iSquirrel5

#define iShowPreview 7
#define iUserItem8

#define kLeftMargin5
#define kTopMargin 40

#define mApple   kBaseResID
#define iAbout   1

#define mFile    kBaseResID+1
#define iSettings1
#define iQuit    3

Dialogger makes use of three globals. gDone is set to true when the program is ready to exit. gShowPreview corresponds to the Show preview checkbox in the Settings... dialog. It is set to true whenever the check box is checked. We could avoid the use of a global by using the same initial setting for Show preview each time we enter the routine that handles the dialog box. By using a global, however, the setting of the check box survives, even after the dialog is dismissed.

/* 3 */

/**************  Globals *************/
Boolean gDone, gShowPreview = true;

The same thinking holds true for gCurrentPICT. This global tells us which picture we’re currently looking at, ensuring that the dialog’s Show preview brings up the current picture of my pet Fred.

/* 4 */

short   gCurrentPICT = kBaseResID;

As always, here’s a complete list of function prototypes.

/* 5 */

/**************  Functions *************/
void    ToolBoxInit( void );
PicHandle LoadPICT( short picID );
void    CreateWindow( void );
void    MenuBarInit( void );
void    EventLoop( void );
void    DoEvent( EventRecord *eventPtr );
void    HandleMouseDown( EventRecord *eventPtr );
void    HandleMenuChoice( long menuChoice );
void    HandleAppleChoice( short item );
void    HandleFileChoice( short item );
void    DoUpdate( EventRecord *eventPtr );
void    DoDialog( void );
void    FlipControl( ControlHandle control );
void    DrawPreview( DialogPtr dialog, short picID );
void    SwitchPICT( void );

The following two routines are part of System 7, and won’t work with outdated versions of the operating system. Remember, you should be using System 7 - no excuses!

The reason the trap addresses are listed in the source code (they’re usually listed in the appropriate #include file) is that they’re not part of the current set of #include files that come with THINK C.

/* 6 */

/* see tech note 304 */
pascal OSErr SetDialogDefaultItem(DialogPtr theDialog, 
 short newItem) 
    = { 0x303C, 0x0304, 0xAA68 };        
pascal OSErr SetDialogCancelItem(DialogPtr theDialog, 
 short newItem)
    = { 0x303C, 0x0305, 0xAA68 };

main() initializes the Toolbox, then sets up the menu bar and creates the My Pet Fred window. Once that’s done, the main event loop is entered.

/* 7 */

/******************************** main *********/

void  main( void )
{
 ToolBoxInit();
 MenuBarInit();
 
 CreateWindow();
 
 EventLoop();
}

Nothing new here...

/* 8 */

/*********************************** ToolBoxInit */
void  ToolBoxInit( void )
{
 InitGraf( &thePort );
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs( NULL );
 InitCursor();
}

LoadPICT() uses GetPicture() to load a PICT resource. If the PICT can’t be found, beep once, then exit.

/* 9 */

/******************************** LoadPICT *********/
PicHandle LoadPICT( short picID )
{
 PicHandlepic;
 
 pic = GetPicture( picID );
 
 if ( pic == NULL )
 {
 SysBeep( 10 );  /*  Couldn't load the PICT resource!!!  */
 ExitToShell();
 }
}

CreateWindow() loads the current PICT, then uses the Rect that defines its border to define the size of a new window. The idea here is to create a window exactly big enough to hold the entire PICT. Of course, this wouldn’t be a good idea if the PICT was bigger than the entire screen. Hmmm... Is this an idea for a column on scroll bars? We’ll see...

/* 10 */

/******************************** CreateWindow *********/
void  CreateWindow( void )
{
 WindowPtrwindow;
 PicHandlepic;
 Rect   r;
 
 pic = LoadPICT( gCurrentPICT );
 
 r = (**pic).picFrame;

We really don’t care where on the screen the PICT is, we just care about its size. We’ll use OffsetRect() to normalize the Rect, moving it so it’s the size of the PICT, but so its upper-left corner is at the point (kLeftMargin, kTopMargin).

/* 11 */

 OffsetRect( &r, kLeftMargin - r.left, kTopMargin - r.top );

Next, we use NewWindow() to create a new window. We could have used GetNewWindow() but we’d have to change the window’s size. Whatever floats your boat...

/* 12 */

 window = NewWindow( NULL, &r, "\pMy Pet Fred", kVisible, 
 noGrowDocProc, kMoveToFront, kNoGoAway, 0L );

If the window couldn’t be created, beep once, then exit.

/* 13 */

 if ( window == NULL )
 {
 SysBeep( 10 );  /*  Couldn't load the WIND resource!!!  */
 ExitToShell();
 }

Since we created the window as kVisible, this call to ShowWindow() is reduntant. I prefer to leave it in, so it’s very obvious when I revisit the code at 3 in the morning.

/* 14 */

 ShowWindow( window );
 SetPort( window );
}

MenuBarInit() does the usual, loading the MBAR resource, adding the apple items to the menu, then drawing the menu bar.

/* 15 */

/****************** MenuBarInit ***********************/
void  MenuBarInit( void )
{
 Handle menuBar;
 MenuHandle menu;
 
 menuBar = GetNewMBar( kBaseResID );
 SetMenuBar( menuBar );
 menu = GetMHandle( mApple );
 AddResMenu( menu, 'DRVR' );
 
 DrawMenuBar();
}

EventLoop() and DoEvent() should be familiar to you. No big changes.

/* 16 */

/******************************** EventLoop *********/
void  EventLoop( void )
{
 EventRecordevent;
 
 gDone = false;
 while ( gDone == false )
 {
 if ( WaitNextEvent( everyEvent, &event, kSleep, NULL ) )
 DoEvent( &event );
 }
}

/************************************* DoEvent      */
void  DoEvent( EventRecord *eventPtr )
{
 char   theChar;
 
 switch ( eventPtr->what )
 {
 case mouseDown: 
 HandleMouseDown( eventPtr );
 break;
 case keyDown:
 case autoKey:
 theChar = eventPtr->message & charCodeMask;
 if ( (eventPtr->modifiers & cmdKey) != 0 ) 
 HandleMenuChoice( MenuKey( theChar ) );
 break;
 case updateEvt:
 DoUpdate( eventPtr );
 break;
 }
}

As you’ve seen in other programs, HandleMouseDown() processes the latest mouseDown event.

/* 17 */

/************************************* HandleMouseDown */
void  HandleMouseDown( EventRecord *eventPtr )
{
 WindowPtrwindow;
 short  thePart;
 long   menuChoice;
 GrafPtroldPort;
 long   windSize;
 Rect   growRect;

FindWindow() tells you which window, and which part of the window, the mouseDown occurred in.

/* 18 */

 thePart = FindWindow( eventPtr->where, &window );

Depending on the part of the window the mouseDown occurred in, the event is handled accordingly.

/* 19 */

 switch ( thePart )
 {
 case inMenuBar:
 menuChoice = MenuSelect( eventPtr->where );
 HandleMenuChoice( menuChoice );
 break;
 case inSysWindow : 
 SystemClick( eventPtr, window );
 break;
 case inContent:
 SelectWindow( window );
 break;
 case inDrag : 
 DragWindow( window, eventPtr->where, 
 &screenBits.bounds );
 break;
 }
}

HandleMenuChoice() handles menu selections from either the • or File menus.

/* 20 */

/****************** HandleMenuChoice ********************/
void  HandleMenuChoice( long menuChoice )
{
 short  menu;
 short  item;
 
 if ( menuChoice != 0 )
 {
 menu = HiWord( menuChoice );
 item = LoWord( menuChoice );
 
 switch ( menu )
 {
 case mApple:
 HandleAppleChoice( item );
 break;
 case mFile:
 HandleFileChoice( item );
 break;
 }
 HiliteMenu( 0 );
 }
}

HandleAppleChoice() is the same as in previous programs.

/* 21 */

/****************** HandleAppleChoice *******************/
void  HandleAppleChoice( short item )
{
 MenuHandle appleMenu;
 Str255 accName;
 short  accNumber;
 
 switch ( item )
 {
 case iAbout:
 NoteAlert( kAboutALRTid, NULL );
 break;
 default:
 appleMenu = GetMHandle( mApple );
 GetItem( appleMenu, item, accName );
 accNumber = OpenDeskAcc( accName );
 break;
 }
}

HandleFileChoice() starts off by declaring a totally useless (and unused) variable. Feel free to delete this line of code. I don’t know what I was thinking!

/* 22 */

/****************** HandleFileChoice ********************/
void  HandleFileChoice( short item )
{
 short  newPICTid;

If Settings... was selected, call DoDialog() to put up the dialog box. If Quit was selected, set gDone to true which will cause the program to drop out of the main event loop.

/* 23 */

 switch ( item )
 {
 case iSettings:
 DoDialog();
 break;
 case iQuit:
 gDone = true;
 break;
 }
}

DoUpdate() gets called whenever the Window Manager generates an updateEvt, asking Dialogger to redraw the contents of the My Pet Fred window.

/* 24 */

/********************************** DoUpdate  */
void  DoUpdate( EventRecord *eventPtr )
{
 PicHandlepic;
 WindowPtrwindow;
 Rect   r;

The WindowPtr is embedded in the event’s message field. We’ll need this in a bit.

/* 25 */

 window = (WindowPtr)eventPtr->message;

Since the window was created the exact size of the current picture, we’ll load the PICT, make window the current port, then draw the PICT in the window.

/* 26 */

 pic = LoadPICT( gCurrentPICT );


 
 SetPort( window );
 
 BeginUpdate( window );
 
 r = window->portRect;
 DrawPicture( pic, &r );
 
 EndUpdate( window );
}

DoDialog() is where the real action is.

/* 27 */

/************************************* DoDialog     */
void  DoDialog( void )
{
 DialogPtrdialog;
 BooleandialogDone = false;
 short  itemHit, itemType;
 Handle itemHandle;
 Rect   itemRect;
 short  curRadioButton;
 PicHandlepic;

GetNewDialog() loads a DLOG resource (as well as its associated DITL resource) with the id specified in the first parameter. The second parameter allows you to designate a filter function that will get called repeatedly as events occur inside your dialog. (We won’t use this filter function here. Maybe in a future column). The third parameter determines whether the dialog’s window appears in front of all other windows, just like the corresponding parameter in GetNewWindow().

/* 28 */

 dialog = GetNewDialog( kDialogResID, NULL, kMoveToFront );

Just as you would with a window, make the dialog visible and make it the current port. As you’ll see, DialogPtrs and WindowPtrs are quite similar and DialogPtrs can be passed to the same routines you’d normally pass a WindowPtr to.

/* 29 */

 ShowWindow( dialog );
 SetPort( dialog );

SetDialogDefaultItem() tells the Dialog Manager which button is the default button (normally the OK button). The default button is the button you’d like activated when the user hits the return key or presses enter. The Dialog Manager will make sure to draw a bold outline around the default button, making it easy for the user to see.

/* 30 */

 SetDialogDefaultItem( dialog, ok );

SetDialogCancelItem() performs a similar function, allowing you to specify the button that gets activated when the user types . (normally the Cancel button). ok and cancel are predefined in a #include file to be 1 and 2 respectively.

/* 31 */

 SetDialogCancelItem( dialog, cancel );

This next calculation tells us which of our three radio buttons should be turned on. Radio buttons always travel in sets. Just like the channel selector buttons on your car radio, one button is always selected, and the others always off. When a radio button is selected its circle is filled in, like the Elephant radio button in Figure 3.

Figure 3. A set of radio buttons.

/* 32 */

 curRadioButton = gCurrentPICT - kBaseResID + kFirstRadio;

GetDItem() uses a dialog item’s id to retrieve its type, a handle to it, and its bounding Rect. We’ll cast the retrieved handle to a ControlHandle, then use the Control Manager routine SetCtlValue() to set the value of the radio button control to kOn. As you can see, radio buttons have two legal values, on (1) and off (0). All controls have a limited range of values. Buttons, radio buttons, check boxes, and scroll bars are all examples of controls.

/* 33 */

 GetDItem( dialog, curRadioButton, &itemType, 
 &itemHandle, &itemRect );
 SetCtlValue( (ControlHandle)itemHandle, kOn );

If the Show preview check box is supposed to be checked, we’ll use GetDItem() and SetCtlValue() to turn it on. By default, all dialog item controls are off.

/* 34 */

 if ( gShowPreview )
 {
 GetDItem( dialog, iShowPreview, &itemType, &itemHandle, &itemRect );
 SetCtlValue( (ControlHandle)itemHandle, kOn );
 }

Our last step in preparing our dialog box is to call our own DrawPreview() function. DrawPreview() checks to see if the Show preview check box is checked. If so, it will draw the miniature picture of My Pet Fred. Otherwise, DrawPreview() will erase any existing preview, then exit.

/* 35 */

 DrawPreview( dialog, curRadioButton + kBaseResID - kFirstRadio );

OK. Now our setup work is done. We’ve set our controls to their initial values, and performed any necessary drawing. This is typical of dialog management. Now we’ll enter the dialog loop, which will bring our dialog to life. The dialog loop keeps going until we set dialogDone to true. We’ll do this when either the Cancel or OK buttons gets pressed.

/* 36 */

 while ( ! dialogDone )
 {

King of all Dialog Manager routines, ModalDialog() grabs an event from the event queue, calls the filter function (if you’ve specified one), then processes the event. ModalDialog() sets itemHit to the item clicked in (if the event was a mouseDown).

/* 37 */

 ModalDialog( NULL, &itemHit );

Now all you have to do is figure out what to do with itemHit.

/* 38 */

 switch( itemHit )
 {

If the click was in the OK or Cancel buttons, set dialogDone to true.

/* 39 */

 case ok:
 case cancel:
 dialogDone = true;
 break;

If the click was in the Show preview check box, we’ll flip the value of the check box (turn it on if off, off if it was on) then call DrawPreview() to redraw the preview area accordingly.

/* 40 */
 case iShowPreview:
 GetDItem( dialog, iShowPreview, &itemType,
 &itemHandle, &itemRect );
 FlipControl( (ControlHandle)itemHandle );
 
 DrawPreview( dialog, curRadioButton + 
 kBaseResID - kFirstRadio );
 break;

If one of the radio buttons was clicked, we first check to make sure it wasn’t the lit one. If the lit one was clicked, there’s no reason to do anything.

/* 41 */

 case iAfghan:
 case iElephant:
 case iSquirrel:
 if ( curRadioButton != itemHit )
 {

If a new one was clicked, turn off the current button, then turn on the new one. Always turn off the old button before you turn on the new one. That way you won’t ever have two radio buttons lit at the same time. This can be jarring to the user.

/* 42 */

 GetDItem( dialog, curRadioButton, &itemType,
 &itemHandle, &itemRect );
 FlipControl( (ControlHandle)itemHandle );
 
 GetDItem( dialog, itemHit, &itemType,
 &itemHandle, &itemRect );
 FlipControl( (ControlHandle)itemHandle );

Next, make curRadioButton reflect the new current radio button, then redraw the preview.

/* 43 */

 curRadioButton = itemHit;
 
 DrawPreview( dialog, curRadioButton + 
 kBaseResID - kFirstRadio );
 }
 break;
 }
 }

Once we drop out of the main dialog loop, we’ll make the dialog window invisible. Even though it’s invisible, we’ll still have access to its controls, so we can change some things then make it visible again if we want.

/* 44 */

 HideWindow( dialog );

If the dialog was dismissed with a click in Cancel, we don’t care about any changes made since the dialog was opened. If the click was in OK (if the user pressed return or enter the Dialog Manager is nice enough to simulate the appropriate click for us), we’ll save the current value of the Show preview check box in gShowPreview.

/* 45 */

 if ( itemHit == ok )
 {
 GetDItem( dialog, iShowPreview, &itemType,
 &itemHandle, &itemRect );
 if ( GetCtlValue( (ControlHandle)itemHandle ) == kOn )
 gShowPreview = true;
 else
 gShowPreview = false;

Next, if the state of the radio buttons has changed, we’ll call the routine SwitchPICT() to switch the My Pet Fred window to reflect our new choice for a domestic destructive device.

/* 46 */

 if ( gCurrentPICT != curRadioButton +
 kBaseResID - kFirstRadio )
 {
 gCurrentPICT = curRadioButton +
 kBaseResID - kFirstRadio;
 SwitchPICT();
 }
 }

Either way, once we’re done, we call DisposDialog() (note the lack of an e in Dispos) to free up all memory allocated for the dialog. If we hadn’t made the dialog invisible first, this would have done that for us.

/* 47 */

 DisposDialog( dialog );
}

FlipControl() calls GetCtlValue() to retrieve the current value of the control, then uses ! and SetCtlValue() to flip its value.

/* 48 */

/****************************** FlipControl   */
void  FlipControl( ControlHandle control )
{
 SetCtlValue( control, ! GetCtlValue( control ) );
}

DrawPreview() first checks to see if the Show preview check box is off.

/* 49 */

/****************************** DrawPreview   */
void  DrawPreview( DialogPtr dialog, short picID )
{
 PicHandlepic;
 short  itemHit, itemType;
 Handle itemHandle;
 Rect   itemRect;

 GetDItem( dialog, iShowPreview, &itemType, 
 &itemHandle, &itemRect );
 if ( GetCtlValue( (ControlHandle)itemHandle ) == kOff )
            {

If so, the preview area is erased and DrawPreview() returns.

/* 50 */

 GetDItem( dialog, iUserItem, &itemType, 
 &itemHandle, &itemRect );
 EraseRect( &itemRect );
 return;
 }

If the check box is checked, the current picture is drawn in the rectangle specified by the user item. As you can see, the user item comes in handy for marking a rectangle in your dialog box. If you want to move the preview area, just go into ResEdit and drag it around or resize it and your changes are reflected next time you run your program.

/* 51 */

 pic = LoadPICT( picID );
 
 GetDItem( dialog, iUserItem, &itemType, 
 &itemHandle, &itemRect );
 FrameRect( &itemRect );
 
 InsetRect( &itemRect, 1, 1 );
 DrawPicture( pic, &itemRect );
}

SwitchPICT() deletes the front window, then creates a new window. Since CreateWindow() uses the current picture to determine the size and contents of its window, the newly selected pet Fred candidate will appear.

/* 52 */

/******************************* SwitchPICT   */
void  SwitchPICT( void )
{
 WindowPtrwindow;
 
 window = FrontWindow();
 DisposeWindow( window );
 
 CreateWindow();
}

Where To Next?

Wow, these columns are getting long! That’s the price we pay as we dive deeper into the Toolbox, I guess. Dialogger demonstrated a modal dialog, a dialog that obscured all other activity until you dismissed it. Next month, I’ll show you how to create a modeless dialog, a dialog that offers all the normal benefits of the Dialog Manager, but coexists with your programs other windows.

Before I sign off, I wanted to take a moment to mention an experience I had with Global Village, a company that makes modems. Not only do they make cool products (they’re the ones who came up with the “hold the option key down and Print... turns to Fax...” strategy) but their customer support is awesome. I had a problem with my modem and they got me back up and running incredibly quickly. Thanks!

Well, I’ll see you next month. Till then, read the Dialog and Control Manager chapters in Inside Macintosh...