Tips on NSApp’s ModalForWindow, NSAlert’s ModalForWindow, and ModalSession

It took me quite a bit of experimentation to clear up some confusion over Objective-C’s “ModalForWindow” language and, subsequently, how to use a modal session. Maybe the following tips will save somebody some time:

(In case you’re new to the concept: When a window, usually a panel, runs modal, it prevents some other part of the app from responding until it has been dismissed.)

“ModalForWindow” means different things in different circumstances. If you are using loadNibNamed to display a panel defined by a xib and you want it to run modal, call this once it is displayed:

// Make panelReviewImports modal, so that no other part of app will respond.
[[NSApplication sharedApplication] runModalForWindow:self.panelReviewImports];

and follow up with this in its dismissal methods:

[[NSApplication sharedApplication] stopModal];

But for NSAlert, the “window” in beginSheetModalForWindow refers to the window to which the alert will be attached as a sheet, which window will be frozen until the alert is dismissed. But the app won’t be frozen; all other windows will remain operable. If you want to attach an alert as a sheet and also freeze the rest of the app, follow the beginSheet code with a simple call to runModal and use the return code explicitly, like this:

[alert beginSheetModalForWindow:self.window 
                  modalDelegate:self didEndSelector:@selector(abandonmentAlertDidEnd:returnCode:contextInfo:) 
                    contextInfo:nil];
NSInteger returnCode = [alert runModal];
[self abandonmentAlertDidEnd:alert returnCode:returnCode contextInfo:nil];

(Of course, you will have implemented the abandonmentAlertDidEnd:returnCode:contextInfo: code as a class method.)

Or, if you want the alert to run as a centered panel, call runModal by itself.

Suppose you want to run a panel modal, f