TweetFollow Us on Twitter

Extend Modal Dialog
Volume Number:6
Issue Number:4
Column Tag:C Workshop

Related Info: Dialog Manager Event Manager

Extending Modal Dialogs

By Paul Potts, Wooster, OH

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

The Gauntlet is Thrown Down

A few months ago I was developing a program that used a modal dialog. I showed the results to my roommate. He ran the program and brought up the dialog, but was then interrupted. When he got back, the screen saver had come on. He moved the mouse to refresh the screen, and then scrutinized my display.

“Which button is default?” he asked .

“That one. The program drew the outline, but it got erased.”

“It should be there.”

“Oh, come on! The Finder doesn’t even keep the outline around its default buttons when you use a screen saver!”

“If it’s in Inside Macintosh, it should be there. Go fix it. Here, make me a copy first.” He popped in a blank disk. Nothing happened.

“How come it didn’t ask if I want to initialize the disk?”

“That doesn’t work when a modal dialog is active,” I explained lamely.

He then pressed the “Q” key. Nothing happened. “There’s a dialog button called Quit -- why didn’t it quit?” he asked. “What kind of user-friendly program is this, anyway?”

The Gauntlet is Picked Up

My roommate was right. We are used to putting up with the limitations of modal dialogs, but ModalDialog can be extended using filter procedures. The parameters of ModalDialog can be declared in C as follows:

/* 1 */

void ModalDialog (filterProc, itemHit)
 ProcPtr  filterProc;
 int  *itemHit;

The address of your filter procedure gets passed by casting it to a procPtr. If you don’t want to use a filterProc, you pass NIL as your first parameter. If you do use a filterProc, Modal dialog then gets each event for you, using a mask which excludes disk events, and sends them to your filterProc. It is then up to your filterProc to decide what to do with them. ModalDialog expects your filterProc to be declared as follows:

/* 2 */

pascal Boolean FProc(Dialog, Event, itemHit)
 DialogPtrtheDialog;
 EventRecord*theEvent;
 int  *itemHit;

A dialog filterProc is actually a function that returns a Boolean value. This value should be TRUE if you want ModalDialog to exit, and FALSE otherwise. ModalDialog passes your filterProc a pointer to the current event. You then can do what you want with it. If your function returns FALSE, ModalDialog will handle the event after you. Thus, you can get a crack at each event even before ModalDialog does. Your filterProc can then do any of the following:

1) Handle the event, then send it to ModalDialog

2) Handle the event and tell ModalDialog to exit

3) Change the event and return to ModalDialog

4) Read the event queue itself and act on it.

My filterProc uses the first technique to handle updateEvents before ModalDialog gets them. This allows me to redraw the default box around a button and then tell ModalDialog to do its own updating. I use the second technique to exit ModalDialog if my filterProc receives a key event that it understands. I use the third technique to handle the <return> key by changing the event from a keypress to a click in the default button. You don’t actually have to do this for <enter> and <return> keypresses, since ModalDialog handles key events, but I wanted to illustrate the technique of altering an event.

Scott Knaster, in Macintosh Programming Secrets, suggests that command-key equivalents be provided for buttons in modal dialog boxes whenever possible. Command-key equivalents aren’t always necessary, however. Some popular applications, such as Microsoft Word, provide single-key equivalents for button clicks, if no editable text fields are present in the dialog, such as in the Save Changes Before Closing dialog. I suggest that commnad-key equivalents be used in modal dialogs with editable text fields, and single-key equivalents (or both single-key and command-key equivalents) be used when no editable text fields are present. My code illustrates both techniques, but your application should use only one. Even though my modal dialog has an editable text field, I allows the user to press a 1, 2, or 3 to choose one of my three buttons. The user can also use <command>-F, S, and T to choose the first, second, and third dialog items, respectively. NOTE: You must make certain that the editText item(s) in the DITL resource that you use are set to Disabled, or else my technique will not work.

When drawing your dialogs with ResEdit, keep in mind that the command-key character is ASCII 17 in the Chicago font, but cannot be typed directly from the keyboard. Microsoft Word will generate this character if you use the Change function to replace a specified character with a ^17. You can then copy this character and paste it into your ResEdit fields. RMaker can generate this character by using \11.

Since ModalDialog does not pass disk events to the filterProc, I use the fourth technique to allow the user to insert a blank disk while the ModalDialog is active. It gets initialized by DIBadMount, which then mounts it (or ejects it, if initialization failed). This might be useful in a modal dialog which displays on-line volumes. SFPutFile uses this technique to allow disks to be mounted while its dialog is active.

There are other ways you can handle events in a modal dialog using filterProcs. You can do anything you want during null events. You can plot a series of icons in your dialog to give the appearance of animation, or draw the current time using DrawString. After all, you have the current grafPort, and can draw directly with QuickDraw. Remember, though, that your drawing operations should be as fast as possible, and must take much less than a single tick to work effectively. Also, remember your poor end-user: don’t make your dialogs overly confusing or complex. We want to extend the Macintosh interface, not bury it.

If you like my code, you are welcome to use it “as-is,” modify it, or completely rewrite it. I’d appreciate it if you’d put my name somewhere in your application, but you can drop me a postcard instead.

Listing:  driveDialog.c

/* This Think C 3.02/4.0 code should be compiled with MacHeaders turned 
on.  Create a new project called FilterProc.Π, and add this file, driveDialog.c, 
along with HandleDialog.c and MacTraps.  Prototypes are provided. Compile 
the resource file, FilterProc.r, with RMaker and put it in the folder 
with the FilterProc project.*/

/*********************************************/
/* File: driveDialog.c */
/* A simple driver application for the dialog
handler.  Your own application would call
it instead. */
 
void main (void);
int HandleDialog(short ID);

void main()
{
 int  itemHit,
/* Dialog item hit, returned by HandleDialog */
 counter;
 
 InitGraf(&thePort);
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs(0L);
 FlushEvents(everyEvent, 0);
 InitCursor();
 
/* Now send the HandleDialog function the resource ID of the DLOG to 
use */
 itemHit = HandleDialog ((short)1);
 
/* Now beep to tell us what item number the HandleDialog call sent back 
(i.e., what item was hit to exit ModalDialog */
 for (counter = 1; counter<= itemHit;  counter++)
 SysBeep(40);
}
Listing:  HandleDialog.c

/*****************************************/
/* File HandleDialog.c */
/*****************************************/
/* Prototypes */
 
int HandleDialog(short Dialog_ID);
/* Called whenever you want to put up a modal dialog */

pascal Boolean FProc(DialogPtr theDialog, 
 EventRecord *theEvent, 
 int *itemHit);
/* Filter procedure called by ModalDialog to screen dialog events */
 
Point CenterDialogItem(DialogPtr theDialog,              int   item_number);
/* Returns the center of the rect of a dialog item, to be called from 
a filter proc while a modal dialog is active. */

void FlashDialogItem(DialogPtr theDialog, int                  item_number);
/* Flashes an item of a dialog, to be called from a filter proc while 
a modal dialog is active. */

void HandleUpdate(DialogPtr theDialog);
/* Used to handle update events while a modal 
dialog is active, called from a filter proc.*/

/********************************************/
/* This procedure returns the center of a dialog item as a point.  It 
is designed to be used with buttons, but will work with any type of dialog 
item.  */
/* Input: theDialog (a DialogPtr), item number (an integer) */
/* Output: a point */

Point CenterDialogItem(theDialog, item_number)
 DialogPtr  theDialog;
 int    item_number;

{
 Point  the_center; /* Center of item, to return */
 int    itemType; /* Returned by GetDItem but not used */
 Handle theItem; /* Returned by GetDItem but not used */
 Rect the_Rect; /* Returned by GetDItem */

GetDItem(theDialog, item_number, &itemType,        &theItem, &the_Rect);
the_center.h = the_Rect.left +   ((the_Rect.right -      the_Rect.left)/ 
2);
the_center.v = the_Rect.top + ((the_Rect.bottom - the_Rect.top)/ 2);
return the_center;
}

/********************************************/
/* This procedure returns the center of the rectangle of the default 
dialog item as a single point.  */
/* Input: theDialog (a DialogPtr), item_number (an integer) */
/* Output:  none */

void FlashDialogItem(theDialog, item_number)
 DialogPtr  theDialog;
 int    item_number;
{
 long tickScratch; /* returned by Delay, unused */
 int  itemType; /* Returned by GetDItem but not used */
 Handle the_item; /* Handle to default button */
 Rect controlRect; /* Returned by GetDItem but not used */

GetDItem(theDialog, item_number, &itemType,  &the_item, &controlRect);
HiliteControl(the_item, 1); 
Delay(6, &tickScratch);
}

/********************************************/
/* The following function handles update events for your dialog box. 
 It is called whenever the filterProc receives an update event.  You 
can put whatever you want to be drawn in the dialog in it.  Right now 
it redraws the rounded rect around the default button (number one). */

/* Constants for drawing roundRect */
#define edgeCurve16
#define gapBetween -4
#define lineSize 3

void HandleUpdate(theDialog)
 DialogPtr theDialog;
{
 Rect controlRect; /* rectangle of the default control.  We
need this to draw the round rect. */
 int    itemType; /* Returned by GetDItem but not used */
 Handle the_item; /* ditto */
 Rect border; /* Rect of the thick border */
 
PenSize(lineSize, lineSize);
/* Get control #1’s rectangle and grow it a little bit, then call FrameRoundRect 
to draw it. */
GetDItem(theDialog, (int)1, &itemType, &the_item, &controlRect);
border = controlRect;
InsetRect(&border, gapBetween, gapBetween);  
FrameRoundRect(&border, edgeCurve, edgeCurve);     
}

/********************************************/
/* The following filterProc is used to handle extra events during the 
modal dialog loop, such as update events.  Its original purpose was to 
keep the default round-rect drawn around the control even after a screen 
saver has redrawn the screen. It also handles insertion of blank disks 
and button-keyboard equivalents. 
NOTE:  If you have one or more editable text fields within your modal 
dialog, your key equivalents should use the command key.  If you don’t 
have any editable text fields, your key equivalents can be handled straight. 
 The names of your buttons should all begin with unique first letters, 
and if you use command-key entry you should provide a legend of command-key 
equivalents next to the buttons. */
 
pascal Boolean FProc(theDialog,  theEvent, itemHit)
 DialogPtrtheDialog;
 EventRecord   *theEvent;
 int    *itemHit;
{
 long key; /* Holds the key code */
 Point  ctr; /* where the mouse click will go */
 int  DIResult; /* Returned by DIBadMount */
 EventRecorddiskEvent; /* Returned by EventAvail, below */

/* Since ModalDialog doesn’t handle bad disk mounts, we have a handler 
that will allow the user to format new disks with a modal dialog still 
on the screen. */

if (GetNextEvent(diskMask, &diskEvent) ==    TRUE)
{
 if (HiWord(diskEvent.message) != 0) 
 {
 diskEvent.where.h = ((screenBits.bounds.right
 - screenBits.bounds.left)/ 2) - (304 / 2);
 diskEvent.where.v = ((screenBits.bounds.bottom
 - screenBits.bounds.top)/  3) - (104 / 2);
 InitCursor();
 DIResult = DIBadMount(diskEvent.where, 
 diskEvent.message);
 }

} /* end of if GetNextEvent test for disk events */

switch (theEvent->what)
{
 case (updateEvt):
 HandleUpdate(theDialog);
 return FALSE;
/*Do not return an item hit value.  Returning
FALSE tells modalDialog to handle the update
event.  We have just added our own handling of the event. */
 break; 
 
 case (keyDown):
 key = theEvent->message & charCodeMask;
 switch(key)
 { 
/* key has been pressed, we want to interpret it properly. */
 case 13: /* Return key */
 { 
 FlashDialogItem(theDialog, 1);
 ctr = CenterDialogItem(theDialog, 1);

/* We can do it this way: change the event record to fool ModalDialog. 
 ModalDialog doesn’t flash the button long enough for my taste, so I 
flash it some more myself. */
 theEvent->what = mouseDown;
 LocalToGlobal (&ctr);
 theEvent->where = ctr;
 theEvent->message = 0;

/* Now we tell ModalDialog to handle the
event.  It doesn’t suspect a thing! */
 *itemHit = 1;
 return FALSE;
 break;
 }

 case 3: /* the Enter key */
 { 

/* Or we can do it our own way by flashing the button and telling ModalDialog 
to exit. */
 FlashDialogItem(theDialog, 1);
 *itemHit = 1;
 return TRUE;
 break;
 }
 
/* These key equivalents do not rely on the use of the command key.  
You would use these in your modal dialog only if you had no editable 
text fields. */
 case 49: /* 1 key */
 { 
 FlashDialogItem(theDialog, 1);
 *itemHit = 1;
 return TRUE;
 break;
 }

 case 50: /* 2 key */
 { 
 FlashDialogItem(theDialog, 2);
 *itemHit = 2;
 return TRUE;
 break;
 }

 case 51: /* 3 key */
 { 
 FlashDialogItem(theDialog, 3);
 *itemHit = 3;
 return TRUE;
 break;
 }
 
/* These key equivalents for buttons use
the command key, and are appropriate even 
for use in a modal dialog with editable text. */
 
 case 102:/* ASCII F */
 { 
 if (theEvent->modifiers & cmdKey)
 {
 FlashDialogItem(theDialog, 1);
 *itemHit = 1;
 return TRUE;
 break;
 }
 }
 
 case 115:/* ASCII S */
 { 
 if (theEvent->modifiers & cmdKey)
 {
 FlashDialogItem(theDialog, 2);
 *itemHit = 2;
 return TRUE;
 break;
 }
 }

 case 116:/* ASCII T */
 { 
 if (theEvent->modifiers & cmdKey)
 {
 FlashDialogItem(theDialog, 3);
 *itemHit = 3;
 return TRUE;
 break;
 }
 }
 
 default:
 {
 return FALSE; /* Do nothing if another key is chosen. */
 break;
 }
 } /* end of key code switch */
 
case (mouseDown):
 
/* You can insert your own mouse click
handlers here.  ModalDialog takes care of mouse events, but you can do 
do special processing.  For example, ModalDialog does nothing if a mouse 
click
occurs inside a modal dialog but outside of a control, but you could 
do something.  */
 
 return FALSE;
 break;
case (mouseUp):
 return FALSE;
 break;
default:
 return FALSE;
 break; 
/* We don’t handle any other types of events, so these get sent to ModalDialog 
unchanged. */    
 } /* end of switch */
} /* end of filterproc function */

/********************************************/
/* HandleDialog is a function to draw and dispose of a simple modal dialog. 
 It tells ModalDialog to use a filter proc to screen events for the dialog. 


Input: short Dialog_ID - the resource ID
Output: item number of the control that was hit to exit ModalDialog. 
*/

int HandleDialog(dialog_ID)
 short  dialog_ID; 
{
 int  itemHit; /* returned by ModalDialog */
 DialogPtrtheDialog; /* The dialog we will work with */
 GrafPtroldWindow; /* Saves the previous window */       

GetPort(&oldWindow);  /* save current grafPort */
SetDAFont(0);    /* use system font */
/* First, get the dialog from the resource and prepare to execute ModalDialog 
*/
theDialog = GetNewDialog(dialog_ID, (Ptr)0, (WindowPtr)-1);
if (ResError() != noErr)
/* Called if GetNewDialog returns an error.  You can put your own error 
handler here.  In this example we are assuming that the dialog is available 
in the application resource fork */
 {
 SysBeep(40);
 ExitToShell();
 }
 
ShowWindow(theDialog);
SetPort(theDialog);
FlushEvents(everyEvent, 0);
 
/*Modaldialog call should wait until event in active control*/
ModalDialog((ProcPtr)FProc, &itemHit);
DisposDialog(theDialog);
FlushEvents (everyEvent, 0);
SetPort(oldWindow);
/* restore drawing state */
return itemHit;
}
Listing:  Filterproc.r

**************************
* RMaker source file for
* filterProc application
**************************

Filterproc.Π.RSRC
RSRCRSED

Type DITL ;;Text for dialog
,1 ;;Resource number
5;;Number of items

Button Enabled
17 27 37 95
First \11F;;The non-printable character is * ASCII 17 (see text)

Button Enabled
17 108 37 182
Second \11S

Button Enabled
17 200 37 262
Third \11T

editText Disabled
137 86 157 222
This is editable text

staticText Enabled
61 43 115 246
This is an example of a modal dialog with command-key equivalents for 
buttons.
* The above text should be all on one line

Type DLOG ;;modal dialog
,1

90 120 266 420
Visible NoGoAway
5;;proc id
0;;refCon
1;;DITL

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »
Perchang (Games)
Perchang 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Welcome to Perchang! A test of skill and puzzle solving across 60 stunning levels. | Read more »

Price Scanner via MacPrices.net

15-inch Retina MacBook Pros on sale for $200-...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 $200 off MSRP - 15″ 2.5GHz... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $300 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799.... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
ABBYY TextGrabber: 1,000,000 Installs in 5 Da...
ABBYY, an international OCR technologies provider, has announced that their image-to-text application TextGrabber, got installed 1,000,000 times in just five days while being featured by the App... Read more
New SkinIt Waterproof Case For iPhone 6
With its impact and waterproof design, the Skinit Waterproof case provides security and protection to guarantee your phone will get you through even the most demanding outdoor conditions. The impact-... Read more
iMacs on sale for up to $150 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2181.11 $118 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1949... Read more
12-inch 1.1GHz Retina MacBooks on sale for $5...
B&H Photo has 2016 12″ 1.1GHz/256GB Retina MacBooks on sale for up to $50 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1249 $50 off MSRP... Read more
WWDC Announcements Revisited Still Underwhelm...
I was disappointed that no new MacBook hardware was announced at this year’s all-software World Wide Developer’s Conference. Not even a hint about what’s in the development pipeline. Of course, we... Read more
Twelve South Compass 2 iPad Stand Now Availab...
Twelve South has updated its most popular iPad stand, Compass 2, with the introduction of two new colors — Gold and Rose Gold. These new color options n perfectly complement the new Rose Gold iPad... Read more

Jobs Board

*Apple* New Products Testers Needed - Apple...
…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* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
*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* Retail - Multiple Positions, Towson...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Professional Learning Specialist - A...
Job Summary The Apple Professional Learning Specialist is a full-time position for one year with Apple in the Phoenix, AZ area. This position requires a high Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.