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.
Create the
NSAlert
object though the standard Objective-Calloc
-and-init
procedure. Then send the requiredNSAlert
“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];
Invoke the
runModal
method on theNSAlert
object.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 byNSAlertFirstButtonReturn
. The second button that is added appears just to the left of the first and is identified byNSAlertSecondButtonReturn
—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
, orNSRunInformationalAlertPanel
.To create and run an alert sheet, use
NSBeginAlertSheet
,NSBeginCriticalAlertSheet
, orNSBeginInformationalAlertSheet
.To create an alert panel, use
NSGetAlertPanel
,NSGetCriticalAlertPanel
, orNSGetInformationalAlertPanel
.
Copyright © 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-02-04