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
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-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]; |
Invoke the runModal
method on the NSAlert
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 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."]; |
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
.
Last updated: 2009-02-04