Displaying Alert Dialogs

Alert dialogs inform the user of an event and present buttons that let the user choose how to proceed. You may implement alert dialogs by invoking methods of the NSAlert class and by calling special functions.

Using the NSAlert API is the preferred approach if you are writing applications that run on Mac OS v10.3 (or later). You thereby gain the advantages of an object-oriented model as well as additional features, such as the ability to display help information related to the alert dialog.

Using the NSAlert Class

Using the NSAlert API to display an alert dialog involves three simple steps: creating and initializing an NSAlert instance, running the dialog, and interpreting and acting on the user’s choice.

  1. Create the NSAlert object though the standard Objective-C alloc-and-init procedure. Then send the required NSAlert “setter” messages to initialize the alert. Listing 1 gives an example of this.

    Listing 1  Creating and initializing the NSAlert object

    NSAlert *alert = [[NSAlert alloc] init];
    [alert addButtonWithTitle:@"OK"];
    [alert addButtonWithTitle:@"Cancel"];
    [alert setMessageText:@"Delete the record?"];
    [alert setInformativeText:@"Deleted records cannot be restored."];
    [alert setAlertStyle:NSWarningAlertStyle];
  2. Invoke the runModal method on the NSAlert object.

  3. Test the result return from runModal and proceed accordingly.

    Listing 2 illustrates the last two steps.

    Listing 2  Running the dialog and interpreting the result

    if ([alert runModal] == NSAlertFirstButtonReturn) {
        // OK clicked, delete the record
        [self deleteRecord:currentRec];
    [alert release];

    The return code is an enum constant identifying the button on the dialog that the user clicked. The first button added to the dialog (which, in left-to-right scripts, is the one closest to the right edge) is identified by NSAlertFirstButtonReturn. The second button that is added appears just to the left of the first and is identified by NSAlertSecondButtonReturn —and so forth for the third button.

    Make sure that you release the NSAlert instance.

You can also create an NSAlert object directly from an NSError object using the alertWithError: method. You can then modally run the alert, thereby presenting the error information to the user. The method uses the localized description, recovery suggestion, and recovery options encapsulated by the NSError object for the alert's message text, informative text, and button titles, respectively.

As a convenience for compatibility with the older functional API (see “Using the Functional APIs”), you can create NSAlert objects with the class factory method alertWithMessageText:defaultButton:alternateButton:otherButton:informativeTextWithFormat:. This method allows you to retain the earlier constants used to identify the button clicked. Here is an example of how you might invoke this method (with the previous example in mind):

NSAlert *alert = [NSAlert alertWithMessageText:@"Delete the record?"
    defaultButton:@"OK" alternateButton:@"Cancel"
    otherButton:nil informativeTextWithFormat:
    @"Deleted records cannot be restored."];

Using the Functional APIs

You can also call functions to create and display alerts. There are three kinds of functions: