Custom Drop-down window/dialog in Cocoa

Question

What are the alternatives of dialog windows in Cocoa? I need to create a custom dialog (modal) where the user will be able to enter some info and when he/she presses OK, my app will close this dialog and process input. So essentially, I need something like a drop-down window in Xcode when you add a new file (command + N): [not enough reputation to post a screenshot] All I have discovered so far are a few old listings and topics where people say it's called a sheet. But the methods suggested seem deprecated, like

beginSheet: myCustomSheet
            modalForWindow: window
            modalDelegate: self
            didEndSelector: @selector(didEndSheet:returnCode:contextInfo:)
            contextInfo: nil

Are there any other ways? For example, I can create a separate window with its own xib file, is there some kind of setting to make it a "panel" or "sheet"? I'm a bit confused by the terms.

Answer 1

What you want is a "sheet". A sheet is one window which is attached to another and blocks most inputs to the window that it's attached to.

A panel is just a specific kind of window. NSPanel is a subclass of NSWindow. It has some different behaviors and possible styles. You can use a panel as a sheet, but you don't have to and it doesn't make much difference.

Note that a sheet is window-modal, not application modal. That is, it prevents the user from doing other stuff with the window to which it is attached, but doesn't prevent the user from doing stuff in the app's menus or its other windows. Implicit in this is that sheets operate asynchronously. You begin a sheet and then execution continues without the sheet's work having been completed. You should then generally allow flow of execution to return to the main event loop. When the sheet completes, it will call some code that you have specified.

If you need synchronous behavior, use an app-modal dialog instead.

The modern API for presenting a sheet is -[NSWindow beginSheet:completionHandler:]. You send that message to the "normal" window (e.g. document window). The first parameter is the window which is to be the sheet. The completion handler is the code to be run when the sheet completes.

The controls within your sheet would typically target their actions to the window controller for the sheet (just as with any other window). Within the action methods, you would call -[NSWindow endSheet:] or -endSheet:returnCode: on the parent window to complete the sheet and determine the result code which is passed to the completion handler. You can obtain the parent window using the sheetParent property.