by Greg Fiumara

Long time Apple fans know how annoying errors and error messages can be. Figure 1 demonstrates an error message from long ago, in the System 7.x days. Back then, millions of dollars each year was spent into buying books like Macs for Dummies and Sad Macs, Bombs, and Other Disasters and downloading articles from the Tech Info Library all to find out what the error was supposed to mean. Wouldn't be easier if the dialog told you what was wrong and how to fix it? You, as the developer, have the power to change all of this. You can explain the errors and tell your users how to fix their problems. Why not make your error dialog look good at the same time? The following will explain to you how you can:

• Properly write a descriptive error message using the information available,
• Inform your user,
• Make your error dialog pleasing to look at, and
• Make your error dialog compatible with Apple's Human Interface Guidelines (HIG)

Putting Words into the Situation

You may not realize it, but when writing an error message, you really have lots of information that you can give the user. Yet many programmers do not take advantage of this information. For instance, let's say that somewhere in your application, you need to open a file somewhere on the user’s computer. The user absent-mindedly moved or deleted this item, and your application was unable to catch this. Already you have the following four bits of information:

1. The File’s Name (e.g. "Super Important Doc")
2. The File’s Supposed Location (e.g. "Macintosh HD:Documents:Superman")
3. Knowledge that the file is not in the location specified anymore
4. The fact that your application needs this file to run

From this information alone, you can construct a well-worded error message, such as the one pictured in Figure 2.

Now, picture you are using your application and stumble across the error shown in Figure 3:

Wouldn’t you rather see Figure 2?

Something is Wrong; Now What?

You have now gotten past the bare-bones error message. Now it is time to inform the user in depth and tell the user what can be done to solve this error from ever happening again. In the first section we discovered that we had four bits of information.... so far we have only used #1 and #3. In this instance, it is necessary that we do everything we can do locate this missing file, because it is necessary that your application has it. You are now ready to tell the user more information and how to fix the problem.

We know where the file was originally located so why not tell the user that? We don’t want to include the whole absolute path, but we can show the name of the parent directory. With this information, the user can locate the file on his/her hard drive and try to remember if maybe he or she did any deleting in that folder.

Figure 4 shows how the document could look when the parent directory information is included. Let’s go back to the list: #1, #2, and #3 have been scratched out but how about #4? Your application needs this file to run. Without it your application could crash (and produce another error...). If the location of the file is normally stored in your application’s preferences file, we can assume that the file is missing or has been renamed. Why not present this information to your user in your error message? Sometimes it is important to guess and sometimes it is not. In this case, your guess is probably correct. A case where it would not be a good idea to guess is when data could be lost. Figure 5 shows the best error message that it could possibly give.

Taking your time and writing good, descriptive error messages can save you, your support team, and your users LOTS of time and money.

Making your Dialog HIG Compatible

I would not be writing this article for The Interface Mafia without making a mention to the HIG. You have already gotten this far in writing a proper error message, why not go the whole way?

To have a proper dialog, you need to have a special type of window frame, either a Modal Dialog or a Movable Modal Dialog. However, since you are going to be displaying an error in the window, you need change the Mac ProcID of the window. (More information on Mac ProcID’s can be found at the Apple Developer Website). For an Alert Dialog, your Mac ProcID should be 1044, or for a Movable Alert Dialog, 1045. If you test your project after adding these ProcIDs, you will see that the difference is that the dialogs are outlined in red as shown in Figure 6 and 7.

When writing an error, either type of dialog is acceptable, though most people tend to like Movable Alert Boxes, so that they can see what they were doing behind the dialog.

We are almost there... we just need to figure out what else goes in the error dialog. The following list shows THE ONLY items that can be in the error dialog.

• The error message
• A note, caution, or stop icon¹ (different in countries besides the U.S.)
• A help button
• Up to 3 other buttons

In the next sections, we will discuss where in the dialog to put the items.

Which Icon?

In your dialog, you have a choice of 3 icons to put in the upper left corner of your dialog. Let’s go through what each of the icons stand for.

The Note Icon (Figure 8) indicates the least amount of worry for the user, just a slight error. (e.g. "The action 'Delete your Hard Drive,' is not available in this application. Please try another.")

The Caution Icon (Figure 9) indicates a slight worry for the user. A potential danger may exist if the user proceeds. (e.g. "My App has spotted a troublesome document on your Hard Drive. Would you like My App to fix this document? Data may be lost.")

The Stop Icon (Figure 10) indicates that data loss or other disastrous damage is almost certain. You may go no further. (e.g. "You cannot delete your Hard Drive")

Using the above list, it should be fairly easy to determine the icon that is correct for your dialog.

What Buttons?

In the section above, I gave you a list of what could be included in an alert box. You can have up to three buttons, excluding an optional help button. I gave you examples on what each of the icons means, because the amount of buttons you can have is determined by the icon you have.² Once again, view the following list to see how many buttons you should have and what their captions should be.

• Note Icon Dialog: Only one button. This button should, in most cases, be "OK," and should be the default button.
• Caution Icon Dialog: Up to 3 buttons and at least 2. One button should be your "Continue" button with its caption something like "OK," or more specific like "Delete." This button should be the default button. You should also have a "Cancel" button.
• Stop Icon Dialog: One button whose caption is "OK." It should be the default button.

Now how about this help button: what is it? In short, this button should launch your help system, or if your help is on the world wide web, it should launch the URL. The button should be a beveled button with the most recent help icon that there is (Figure 11).³ The button should be in line with the other buttons in your window and should be spaced over to where your error message is. (See “Spacing” below)

A few more steps and you will be done! Can you belive it?

Spacing

This is by far the hardest part of the process. The good part is that I saved it for last. In this section, I will try and let some pictures to the talking. In Figure 12, we see, the proper distances of your icon to your error and button to button (measured in pixels).

Now, we will focus on the buttons. On each side of the captions of the buttons, you should leave 8 pixels of space. This is totally different if your button is an "OK" button. If it is, your button should be 58x20.

You're Finished/Extra Credit

Congratulations... you're finished!

Taking your time and writing good, descriptive error messages can save you, your support team, and your users LOTS of time and money.

Have you found a horrible excuse for an error message? Are you a developer how has good error messages? If you can answer, “yes,” e-mail me at greg@interfacemafia.org of this article and show me.

1. The stop icon is replaced by another icon in some countries where an open palm has offensize meanings. [Return to text]

2. The writers of the HIG thought of everything, and I mean everything. Aren’t you glad you program on a Mac? [Return to text]

3. This article was not written in consideration of Mac OS X, which has different guidelines regarding contextual help. [Return to text]

Links

Macs for Dummies
http://www.dummies.com/

Sad Macs, Bombs, and Other Disasters
http://www.peachpit.com/books/catalog/69963.html

Apple Tech Info Library
http://karchive.info.apple.com/

Macintosh Human Interface Guidelines
http://developer.apple.com/techpubs/mac/HIGOS8Guide/thig-2.html

Macintosh Human Interface Guidelines: Macintosh ProcIDs
http://developer.apple.com/techpubs/macos8/HumanInterfaceToolbox/
WindowManager/WindowMgr8Ref/WindowMgrRef.b.html

[an error occurred while processing this directive]

The Interface Mafia - www.interfacemafia.org
News - About Us - Articles - Reviews - Submit Software - Links - The Mafiosi

this page last updated on Tuesday, October 9, 2001
site design by tobyrush.com - web space by westhost.com
follow this link for copyright information