3.6 Sheets

Sheets implement window modal (as opposed to application modal) dialogs that are attached to the window. Thus, when a dialog pops up asking for attention, it blocks interaction only with that particular window, not the entire application. When a sheet is opened or closed, it appears to slide out of the title bar. Because the sheet is attached to another window, such as a document window, the user never loses track of what dialog belongs with which window. Figure 3-8 shows an example of a sheet.

Figure 3-8. A TextEdit sheet asking if you want to save changes

The Application Kit defines a number of convenient functions for displaying standard alert and message sheets, including NSBeginAlertSheet, NSBegin-InformationalAlertSheet, and NSBeginCriticalAlertSheet. Each function takes the same parameters; they differ only in the icon displayed on the left of the sheet. The function prototype for NSBeginAlertSheet is the following:

void NSBeginAlertSheet(NSString *title, 
                       NSString *defaultButton, 
                       NSString *alternateButton, 
                       NSString *otherButton,
                       NSWindow *docWindow, 
                       id modalDelegate, 
                       SEL didEndSelector, 
                       SEL didDismissSelector, 
                       void *contextInfo, 
                       NSString *msg, ...)

Table 3-2 describes each parameter.

Title

defaultButton

alternateButton

otherButton

docWindow

modalDelegate

didEndSelector

didDismissSelector

contextInfo

msg

An alert similar to the one in Figure 3-8 can be created with a call to NSBeginInformationalAlertSheet, as shown in Example 3-2.

Example 3-2. Creating an alert sheet with NSBeginInformationalAlertSheet

NSBeginInformationalAlertSheet(
            @"Do you want to save changes to \
                     this document before closing?" 
            @"Save", 
            @"Don't Save", 
            @"Cancel", 
            mainWindow, 
            self, 
            @selector(sheetDidEnd:returnCode:contextInfo:), 
            NULL, 
            NULL, 
            @"If you don't save, your changes will be lost.");

You can display any window as a sheet by using APIs provided by NSApplication. To display a sheet, invoke the following method:

beginSheet:modalForWindow:
    modalDelegate:didEndSelector:contextInfo:

The first argument, beginSheet:, is the NSWindow we wish to display as a sheet. The modalForWindow: argument specifies the window to which the sheet is attached. Since application execution continues while a sheet is open, the sheet uses a modal delegate to handle user interaction. This delegate is assigned in the modalDelegate: argument. The callback method is indicated in didEndSelector: and has the following signature:

- (void)sheetDidEnd:(NSWindow *)sheet 
        returnCode:(int)returnCode
        contextInfo:(void *)contextInfo;

In this method, contextInfo: is the object passed in the NSApplication method used to open the sheet. It is used to optionally pass arbitrary information between the creator of the sheet and the modal delegate.

To end a document modal session, use NSApplication's methods endSheet: or endSheet:returnCode:. Each method takes the sheet window as a parameter. The second, endSheet:returnCode:, also takes an integer return code that is passed to the didEndSelector: method. Example 3-3 shows how to open and close a sheet in an application.

Example 3-3. Using sheets in an application

/*
 * This method is invoked to open a sheet.
 * Assume sheetWindow and mainWindow are Interface Builder
 * outlet instance variables connected to windows in a nib.
 */
- (void)openSheet:(id)sender
{
    SEL selector = @selector(sheetDidEnd:returnCode:contextInfo:);

    [NSApp beginSheet:sheetWindow
       modalForWindow:mainWindow
        modalDelegate:self
       didEndSelector:selector
          contextInfo:NULL];
}

/*
 * This could be the action of the "Cancel" button of the sheet
 * in Figure 3-8.
 */
- (void)cancelSheet:(id)sender
{
    [NSApp endSheet:sheetWindow returnCode:NSCancelButton];
}

/*
 * This could be the action of the "Save" button of the sheet
 * in Figure 3-8.
 */
- (void)acceptSheet:(id)sender
{
    [NSApp endSheet:sheetWindow returnCode:NSOKButton];
}

- (void)sheetDidEnd:(NSWindow *)sheet
       returnCode:(int)returnCode
       contextInfo:(void *)contextInfo
{
    /* 
     * Can do something here based on the value of returnCode
     * or do something in the button actions themselves.
     */
    if ( returnCode == NSOKButton ) {
        // If OK was clicked...
    } else if ( returnCode == NSCancelButton ) {
        // If Cancel was clicked....
    }

    [sheet orderOut:nil];
}

In this example, NSOKButton and NSCancelButton are global constants often used to identify those buttons in a dialog. The endSheet: methods only end the document modal session; they do not remove the sheet from the screen. To hide the sheet, send an orderOut: message to the sheet window, which Example 3-3 does in the callback method sheetDidEnd:returnCode:contextInfo:.

Finally, there are yet more ways to display sheets: the AppKit classes that implement standard Mac OS X user interfaces, such as NSPrintPanel and NSOpenPanel, all provide ways to display their respective interfaces as document modal sheets.