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:

• To create and run an alert panel, use NSRunAlertPanel, NSRunCriticalAlertPanel, or NSRunInformationalAlertPanel.

• To create and run an alert sheet, use NSBeginAlertSheet, NSBeginCriticalAlertSheet, or NSBeginInformationalAlertSheet.

• To create an alert panel, use NSGetAlertPanel, NSGetCriticalAlertPanel, or NSGetInformationalAlertPanel.