NSAlert

An alert appears onscreen either as an app-modal dialog or as a sheet attached to a document window. The methods of the NSAlert class allow you to specify alert level, alert text, button titles, and a custom icon should you require it. The class also lets your alerts display a help button and provides ways for apps to offer help specific to an alert.

By design, an NSAlert object is intended for a single alert—that is, an alert with a unique combination of title, buttons, and so on—that is displayed upon a particular condition. You should create an NSAlert object for each alert dialog. Normally you should create an NSAlert object when you need to display an alert, and release it when you are done. If you have a particular alert dialog that you need to show repeatedly, you can retain and reuse an instance of NSAlert for this dialog.

After creating an alert using one of the alert creation methods, you can customize it further prior to displaying it by customizing its attributes. See Instance Attributes

Instance Attributes

NSAlert objects have the following attributes:

Type An alert’s type helps convey the importance or gravity of its message to the user. Specified with the alertStyle property.

Message text The main message of the alert. Specified with messageText.

Informative text Additional information about the alert. Specified with informativeText.

Icon An optional, custom icon to display in the alert, which is used instead of the default app icon. Specified with icon.

Declaration

Objective-C

- init

Return Value

An initialized alert.

Discussion

Unless you must maintain compatibility with existing alert-processing code that uses the function-based API, you should allocate (alloc) and initialize (init) the alert object, and then set its attributes using the appropriate methods of the NSAlert class.

Declaration

Parameters

error

Error information to display.

Return Value

An initialized alert.

Discussion

The NSAlert class extracts the localized error description, recovery suggestion, and recovery options from the error parameter and uses them as the alert’s message text, informative text, and button titles, respectively.

Parameters

Title of the alert. When nil or an empty string, a default localized title is used (“Alert” in English).

defaultButtonTitle

Title for the default button. When nil or an empty string, a default localized button title (“OK” in English) is used.

alternateButtonTitle

Title for the alternate button. When nil, the alternate button is not created.

otherButtonTitle

Title for the other button. When nil, the other button is not created.

informativeText

Informative text. This is optional but must be an empty string (@””) not nil. Can embed variable values using a format string; list any necessary arguments for this formatted string at the end of the method’s argument list. For more information on format strings, see Formatting String Objects.

Return Value

Initialized alert.

Discussion

For languages that read left to right, the buttons are laid out on the bottom-right corner of the alert sheet or window, with defaultButtonTitle on the right, alternateButtonTitle on the left, and otherButtonTitle in the middle. The return values identifying these buttons are constants— NSAlertDefaultReturn, NSAlertAlternateReturn, and NSAlertOtherReturn—that correspond to the keywords.

By default, the first button has a key equivalent of Return, any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it is not the first button). You can also assign different key equivalents for the buttons using the setKeyEquivalent: method of the NSButton class. To access the alert’s buttons, use the buttons property.

Special Considerations

This is a compatibility method. It is designed for easy adoption by apps migrating from the corresponding function-based API. This method uses earlier return values—NSAlertDefaultReturn, NSAlertAlternateReturn, and NSAlertOtherReturn—compatible with the earlier API, rather than the return values defined by the NSAlert class, described in Button Return Values.

Unless you must maintain compatibility with existing alert-processing code that uses the function-based API, you should allocate (alloc) and initialize (init) the object, and then set its attributes using the appropriate methods of the NSAlert class.

Import Statement

Availability

Specifies that the alert must do immediate layout instead of lazily just before display.

Declaration

Swift

funclayout()

Objective-C

- (void)layout

Discussion

You need to call this method only when you need to customize the alert’s layout. Call this method after all the alert’s attributes have been customized, including the suppression checkbox and the accessory layout. After the method returns, you can make the necessary layout changes; for example, adjusting the frame of the accessory view.

Note

The standard alert layout is subject to change in future system software versions. Therefore, if you rely on custom alert layout, you should make sure your layouts work as expected in future releases of OS X.

Availability

Declaration

Discussion

The NSAlert class places the accessory view between the informative text or suppression checkbox (if present) and the response buttons. Before you change the location of the accessory view, first call the layout method.

Adding an accessory view to an alert shows an example of adding an accessory view to an alert. Alert dialog with an accessory view shows the alert generated.

Import Statement

Availability

Declaration

Swift

var showsHelp: Bool

Objective-C

@propertyBOOLshowsHelp

Discussion

Set this property’s value to YEStrue to specify that the alert has a help button, or NOfalse to specify it does not.

When a user clicks an alert’s help button, the alert delegate (delegate) receives a alertShowHelp: message. If there is no delegate, or if the delegate does not implement that method, or if the delegate returns NOfalse, then the openHelpAnchor:inBook: message is sent to the app’s help manager with a nil book and the anchor specified by the helpAnchor property, if set. An exception is raised if the delegate returns NOfalse and no help anchor is set.

Parameters

sheetWindow

The window on which to display the sheet.

handler

The completion handler that gets called when the sheet’s modal session ends.

Discussion

This method uses the NSWindow sheet methods to display the alert (for more information, see Managing Sheets). If the alert has an alert style of NSCriticalAlertStyle, it will be presented as a critical sheet, which means that it can display on top of other sheets that might already be attached to the window. Otherwise, it will be presented—or queued for presentation—as a standard sheet.

Note that orderOut: no longer needs to be called in the completion handler. If you don’t dismiss the alert, it will be done for you after the completion handler finishes.

The alertDidEndSelector argument must be a selector that takes three arguments, and the corresponding method should have a declaration modeled on the following example:

-(void)alertDidEnd:(NSAlert*)

alert

returnCode:(NSInteger)

returnCode

contextInfo:(void*)

contextInfo

;

where alert is the NSAlert object, returnCode specifies which button the user clicked, and contextInfo is the same contextInfo passed in the original message. The returnCode argument identifies which button was used to dismiss the alert (see this method’s “Special Considerations” section). The modal delegate determines which button was clicked (“OK”, “Cancel”, and so on) and proceeds accordingly.

If you want to dismiss the sheet from within the alertDidEndSelector method before the modal delegate carries out an action in response to the return value, send orderOut: (NSWindow) to the window object obtained by sending window to the alert argument. This allows you to chain sheets, for example, by dismissing one sheet before showing the next from within the alertDidEndSelector method. Note that you should be careful not to call orderOut: on the sheet from elsewhere in your program before the alertDidEndSelector method is invoked because the parent window can hang when another alert is requested. If you need to do this, use the NSApplication method endSheet:.

Declaration

Discussion

If you want to customize an alert’s suppression checkbox, access it via this property and then use the methods of the NSButton class. For example, you can do this to change the suppression checkbox’s default message, or to change its initial selection state (which is “unselected” by default). For a code example, see the showsSuppressionButton property.

See Also

Declaration

Discussion

By default, the image used in an alert is the app icon, accessed through the app bundle’s NSApplicationIcon property. If you set this property’s value, your specified custom image is used in place of the app icon.

If you’ve set a custom alert icon, you can clear it by setting this property’s value to nil, which restores use of the app icon for the alert.

Declaration

Discussion

The button displayed rightmost in the alert (for a left-to-right language) corresponds to the button at index 0 in this property’s array, and is considered the default button. A user can invoke this button by pressing the Return key.

Any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it is not the first button). You can also assign different key equivalents for the buttons using the setKeyEquivalent: method of the NSButton class.

Declaration

Parameters

buttonTitle

Title of the button to add to the alert. Must not be nil.

Return Value

Button added to the alert.

Discussion

Buttons are placed starting near the right side of the alert and going toward the left side (for languages that read left to right). The first three buttons are identified positionally as NSAlertFirstButtonReturn, NSAlertSecondButtonReturn, NSAlertThirdButtonReturn in the return-code parameter evaluated by the modal delegate. Subsequent buttons are identified as NSAlertThirdButtonReturn +n, where n is an integer

By default, the first button has a key equivalent of Return, any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it’s not the first button). You can also assign different key equivalents for the buttons using the setKeyEquivalent: method of the NSButton class. In addition, you can use the setTag: method of the NSButton class to set the return value.

Constants

An alert used to warn the user about a current or impending event. The purpose is more than informational but not critical. This is the default alert style.

Available in OS X v10.3 and later.

InformationalAlertStyle

NSInformationalAlertStyle

An alert used to inform the user about a current or impending event.

Available in OS X v10.3 and later.

CriticalAlertStyle

NSCriticalAlertStyle

Reserved this style for critical alerts, such as when there might be severe consequences as a result of a certain user response (for example, a “clean install” will erase all data on a volume). This style causes the icon to be badged with a caution icon.

Available in OS X v10.3 and later.

Discussion

Currently, there is no visual difference between informational and warning alerts. You should only use the critical (or “caution”) alert style if warranted, as specified in the “Alerts” chapter in OS X Human Interface Guidelines.

The user clicked the second button from the right edge of the dialog or sheet.

Available in OS X v10.3 and later.

NSAlertThirdButtonReturn

NSAlertThirdButtonReturn

The user clicked the third button from the right edge of the dialog or sheet.

Available in OS X v10.3 and later.

Discussion

If you have more than three buttons on your alert, the button-position return value is NSAlertThirdButtonReturn + n, where n is an integer. For languages that read right to left, the first button’s position is closest to the left edge of the dialog or sheet.