NSAlert Tutorial

Apple has a whole Sheet Programming Guide, which I found problematic: it mentions did-end and did-dismiss selectors and delegates… which is a little bit of a red herring. In fact, it’s a barrel of herrings-of-all-colours that refers to

[alert beginSheetModalForWindow:...
modalDelegate:...
didEndSelector:...
contextInfo:...];

… which was deprecated in osX 10.10. As of writing, the current version of macOS is 10.13, (even though I still use and target 10.12) and a good many people who started programming with Swift will never have seen this method (or, indeed, much Objective-C code.)

The SheetProgrammingGuide mentions two ways of creating alerts – through functions (disrecommended since 10.3, which was released in 2001, deprecated properly in 10.10) or using the NSAlert class. It does not mention the option of using a sheet segue to create a custom sheet. All of the sample code is in ObjectiveC, and unless I’m mistaken, it would not run without modifications due to its age.

You can find out what Apple thinks about Sheets in the Dialog section of the Human Interface Guide; but the summary seems to be that the use case is dialogs – a print dialog, agreeing to a user agreement, anything that needs the user’s input before continuing. (Read the guidelines; most of the advice should be a no-brainer, but it’s useful to remind oneself of them anyway.) And then read the Alert section of the HIG, too.

One key bit of advice about usage is in the documentation:

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, creating it only when you need to display an alert, and release it when you are done.

But here we also happen across the weirdest and most infuriating aspect of NSAlert: the modal and sheet modal forms have a different lifecyle, and it’s easy to overlook that. For a modal NSAlert, interaction handling (which button was pressed, did the user tick the ‘don’t show this again’ box) happens after showing the alert; the alert is retained as long as it is within scope of the calling function.
For a sheetModal NSAlert, all handling needs to happen in the completion handler; the alert is released immediately afterwards.

When you’re switching from one style to the other, this can catch you out.
handler: The completion handler that gets called when the sheet’s modal session ends should be a clue, but I admit to overlooking it for a good while.

In the documentation for the buttons of an NSAlert, under _Related Documentation_, you will find
An alert’s return values for buttons are position dependent. The following constants describe the return values for the first three buttons on an alert (assuming a language that reads left to right). Note that these constants constitute additional
NSApplication.ModalResponse
values used by
runModal()
and
beginSheetModal(for:completionHandler:)
.

Note that the ‘ButtonReturnValues’ link goes to the same page, but they’re NSApplication.ModalResponse values; more specifically the NSApplication.ModalResponse.alertFirstButtonReturn (.alertSecondButtonReturn, .alertThirdButtonReturn).

0) Before we begin, let’s have a look at the old Functional API.

While the SheetProgrammingGuide still mentions it,
void NSBeginAlertSheet(NSString *title, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, NSWindow *docWindow, id modalDelegate, SEL didEndSelector, SEL didDismissSelector, void *contextInfo, NSString *msgFormat, ...);
has been properly deprecated in 10.10. (It was discouraged in 10.3, which came out in 2001… a long time ago).

It’s an intereresting window into what development used to be like, and it shows one of the strengths of OOP: this might have been ‘functional’ (of sorts), but the NSAlert way is much clearer. Above is code you need to copy and fill in as well as you can, and while it’s cool that you can pass it functions (what should happen when you dismiss the sheet, who should handle the alert etc), it’s also pretty overwhelming. (Note, for instance, that you have items called ‘defaultButton’ etc which are NSStrings. Note also the weak typing in having a modalDelegate of type id, which corresponds to AnyObject.)

1b) Let’s start to customise it a bit.

PROTIP: Create an alert, customise it, then run it. If you do the customisation after showing the alert, you won’t see the effect. (Ask me how I know…). It is assumed that unless I specifically state that you should add code at the top or bottom of this function, all customisations will be between let alert = NSAlert() and alert.runModal()

There are three styles of alert: .informational, .warning, and .critical. Let’s try the other two (.informational is default)

alert.alertStyle = .informational //(see screenshot above)
alert.alertStyle = .warning

(Yeah, me too. Currently, there is no visual difference between informational and warning alerts sez the NSAlert.Style documentation; which does not mean that there never will be.)

The icon automatically uses your application icon, so I’ve added a very simple one to the AssetCatalogue (using AppIconTool from the App Store. The ability to upload a single image to Xcode and have it auto-generate icons is definitely on my wishlist.)

Yeah. Better.

alert.alertStyle = .critical

With and without a custom app icon. This will – see above – look better if you use an icon that isn’t just square, but has some transparent pixels.

If you want to use a custom icon, simply use

alert.icon = #imageLiteral(resourceName: "bluebell")
(replace with your favourite method of instantiating images; these days I prefer adding an image to the AssetCatalogue and using image literals over NSImage(named:)

1c) We move back to .informational (I simply like it better, these alerts do not _need_ my attention), and customise the text.

add
alert.messageText = "This is a standard alert"
alert.informativeText = "It does nothing extraordinary, but like so many alerts, it wants to be confirmed."

This resolves the autolayout issue: Autolayout does not like an empty string for the informativeText.

Text restrictions: Informative Text can be very, very long. Here I’ve pasted two paragraphs from the Human Interface Guidelines; the alert expands downwards to acommodate them. (This is not a good idea, but it’s good to know where the breaking point is.)

At around this point, I’m happy to stop complaining about Autolayout:

I was definitely expecting setting the same two paragraphs as the message text to completely break the alert, it does not. Not that you’d ever want this, but I was expecting anything other than a full line of text to break things somewhat. Instead it’s smooth. Bravo, Apple.

alert.addButton(withTitle: "First")
alert.addButton(withTitle: "Second")
alert.addButton(withTitle: "Third")

gives you

This button placement is automatic; the default button on the right, its counterpart to the left of it, and the opposite action set apart on the left. If you think of them as ‘don’t save, cancel, save’, the pattern becomes clearer.

If the second or third (but not the first!) button is titled ‘Cancel’ (but not ‘cancel’), it will respond to command-period or the Escape key.

2c) Obviously, I now want to break it a bit.

alert.addButton(withTitle: "OK")
alert.addButton(withTitle: "OK")
alert.addButton(withTitle: "OK")

2d) What about the number of buttons? The HIG says An alert can include up to three buttons but who ever listened to that? (Further down, the HIG becomes more explicit: Generally, use two-button alerts. Two-button alerts provide an easy choice between two alternatives. Single-button alerts inform, but give no control over the situation. Alerts with three or more buttons create complexity though I would argue that in many cases – see ‘save’ dialog – you want the ‘do this’ ‘don’t do this’ ‘let me go back to the document and reconsider’ triad.

alert.addButton(withTitle: "First")
alert.addButton(withTitle: "Second")
alert.addButton(withTitle: "Third")
alert.addButton(withTitle: "Fourth")
alert.addButton(withTitle: "Fifth")
alert.addButton(withTitle: "Lots")

NSAlert has a property of var buttons = [NSButton] and there’s no actual physical limit to them. This has a number of advantages, but it does leave alerts open to exploitation).

Please don’t add more than three buttons to your alerts.

2e) Our buttons still don’t do anything, but what if you don’t want the rightmost button to be the default?

There’s a small trap for the unwary here. While the default button is marked by a highlight, setting the highlight state independently will not work.

Experiment:
alert.buttons[0].highlight(false)
alert.buttons[1].highlight(true)

(these are methods of NSButton, the array builds – as we have seen – from right to left.)

A you can see, marking a button as the default overrides any removal of highlighting. On a tangent, I found that you also cannot use a button’s action to set the button’s highlight, because the automatic management – highlight-while-being-clicked – overrides setting the highlight state manually.

So if the default marking of a button is determined by setting its key equivalent to ‘return’, all we need to do is set it for the second button and –

alert.buttons[1].keyEquivalent = "\r"

Well, not quite yet. NSAlert automatically adds the same to the first button, so they’re now both our default buttons. Which is a bad idea. (It’s not _very_ obvious, but if you compare this image with the one above, you see that the highlight state – while also blue with a light text – is subtly different from the default button state. Past incarnations of macOS were more drastic, future incarnations (or skins?) might do the same again, which is another excellent reason not to try and indicate a default button – the one you should choose if you want to be safe/do the thing you meant to – using the unrelated highlight.

You need to specifically set alert.buttons[0].keyEquivalent = "" to make the second button the default.

What happens when you set several buttons to the same key equivalent? In this example, the rightmost button always won, if it was a non-default button, the leftmost button got logged; I did not manage to fire the middle button. This behaviour seems to be consistent even when you choose a different key equivalent (here: “p” which is triggered by pressing the ‘p’ key) – if the rightmost button is part of the group, the rightmostbutton fires, otherwise, it’s the button on the left. I only tried this with three buttons, for reasons that will become obvious later.

Key codes and key masks (basically, the option to specify command-p or option-a) are beyond the scope of this post, so here you’ll only get single letters. Anyway. Give each button a different key equivalent, and let’s move on.

4a) Create a new NSView subclass in your app, name it AlertAccessoryView. Drag a customView from the object library into the bar at the top of your scene (which now should have objects for AlertViewController, FirstResponder, and your custom view) and set its class to AlertAccessoryView. It will appear as a non-resiable or movable view above your AlertViewController scene.
Under 10.12.6 and Xcode 9, I’ve managed to get a resize handle to widen this by dragging a wider object into my view, and had no luck with the ability to resize the height. Setting either in the Size Inspector works fine, though.
Drag a button and a label into the view; details don’t matter right now. For items like this, I like to use a Box, send it to the back, and set its fill colour, which is easier than messing with other ways of colouring a view.

Create an outlet for your custom view @IBOutlet var accessoryView: AlertAccessoryView! which now allows you to set
alert.accessoryView = accessoryView

And hey presto, you’ve got the opportunity to do anything you like in the usual fashion. One good use for the accessory view would be to have two views and a disclosure button – add a ‘show more’ button and tell the user everything they need to know about the action they’re about to perform in one handy place.

5a) First, declare that your ViewController will conform to the NSAlertDelegate protocol, then add

alert.delegate = self

to the body of the function.

5b) Next, implement

func alertShowHelp(_ alert: NSAlert) -> Bool {
let alert = NSAlert()
alert.messageText = "You rang?"
alert.informativeText = "Let me sing of alerts and sheets..."
alert.runModal()

return true
}

which is lousy interface design – two modal alerts on the screen at the same time – but had to be done. In this function, you can implement anything you like. You could even create a code branch: either do a custom thing and return true from the alertShowHelp function, OR set a helpAnchor and return false to redirect to the help system.

It is easy to overlook that runModal() returns a value, the above-mentioned NSApplication.ModalResponse. Replace that line with

let result = alert.runModal()

default:
print("There is no provision for further buttons")
}

and you can catch which button was pressed and act accordingly.

6b) If you look at the documentation, you can see why ‘default’ is necessary: this is not an enum, but a bunch of static variables; so you will never get the complete set. But what of the other two, OK and cancel?

Add
case NSApplication.ModalResponse.OK:
print("OK")
case NSApplication.ModalResponse.cancel:
print("Cancelled")

to your switch statement, comment out the three button-related ones, and make sure that you add only

alert.addButton(withTitle: "OK")
alert.addButton(withTitle: "Cancel")

to your NSAlert. Also remove the key equivalent code – when experimenting, it’s very easy to not add enough buttons to the buttons array and create an out-of-bounds error.

Build, run, and be disappointed: this catches only the default clause.

Remove all the buttons that you have added to the alert so you only get the default OK button that NSAlert adds by default.

Build and Run. This returns NSApplication.ModalResponse.cancel, and at this point I have no idea whether that’s wanted behaviour or a bug. (I would have expected .OK) and I have no idea what will return that.
This default button does not get added to the buttons array, which is consistent with not returning .alertFirstButtonReturn

Sheet Modal Alerts

7) So far, we have only run the NSAlert modally, which means it appears in its own window. Press the help button again if you need a reminder of the behaviour: only the modal window is responsive and can get focus, any other windows can be moved, but not interacted with or dismissed.
NSAlert has a second mode: ‘sheetModal’, which means that it will appear as a drop-down sheet attached to a specific window. This is particularly useful for document-based applications, since the rest of the application will function as normal.

7a) Return the alert to the state where you add three buttons yourself.

alert.addButton(withTitle: "First")
alert.addButton(withTitle: "Second")
alert.addButton(withTitle: "Third")

Comment out the code you wrote in 6a) –
//let result = alert.runModal()
// switch result {
[…]

and replace it with

if let window = view.window {
alert.beginSheetModal(for: window, completionHandler: nil )
}

In examples, I have frequently found NSApp.keyWindow instead of view.window – the currently active window – but ‘window for this view’ seems a better fit. I have not tested this with a multi-window application, so I just want to flag this up here: it may be that the choice of window needs to be made differently. For this example app, both work.

Build and Run.

The alert attaches to the menu bar, and everything works just fine.

7b) beginSheetModal does not return anything, so our switch statement above is useless.

The key lies in the full signature of beginSheetModal:

func beginSheetModal(for: NSWindow, completionHandler: ((NSApplication.ModalResponse) -> Void)? = nil)

If you only have an informational alert, and don’t need a response, you can call this as alert.beginSheetModal(for: window), but I found it useful to have the reminder that there IS provision for a completion handler useful.

The signature tells you that you will get a ModalResponse and don’t need to return anything, and in the meantime you can do anything you like (which usually will correspond to the switch statement above). This isn’t the place to go into closure syntax in detail, but the full code is

if let window = view.window {
alert.beginSheetModal(for: window, completionHandler: {(result) -> Void in
switch result {
case NSApplication.ModalResponse.alertFirstButtonReturn:
print("First (and usually default) button")
case NSApplication.ModalResponse.alertSecondButtonReturn:
print("Second (frequently cancel) button")
case NSApplication.ModalResponse.alertThirdButtonReturn:
print("Third button, (often the dangerous one: Don't save).")

}

Where the function signature gives you the response type, here you provide a local variable name, and then you write code just as you would normally, just making certain you balance the brackets properly. (I frequently write closures first and assign them to a variable, and then simply pass in alertClosure as a parameter, but that’s a personal preference.)

Build and run: apart from the sheet dropping down, you should see no difference to the modal alert.

alert.showsSuppressionButton = true

8b) Get a reference to preferences and add a constant for the key

The beginning of our function is thus:

let defaults = UserDefaults.standard
let alertSupressionKey = "AlertAlertSupression"

switch defaults.bool(forKey: alertSupressionKey){
case false: [alert generation goes here]

(The commented-out line allows you to quickly reset the key during testing. In production, there would be a preference setting, or even a ‘reset all warnings’ option).

8c) Handle the supression button

if alert.suppressionButton?.state == .on {
defaults.set(true, forKey: alertSupressionKey)
}

This code goes either inside the completion handler for a sheetModal alert, or after let result = alert.runModal() for a modal alert.
(This was the ‘different life cycle’ bit mentioned at the start of this article. You cannot run this after beginSheetModal. While the modal alert is retained until the end of the function, the sheetModal is released earlier.)

8d) Close the switch statement with the ‘true’ branch:

case true:
print("User was bored")
}