Using the NSAlert Class

Using the NSAlert API to display an alert sheet involves three simple steps: creating and initializing an NSAlert instance, displaying the sheet, and interpreting and acting on the user’s choice.

1. Create the NSAlert object though the standard Objective-C alloc-and-init procedure. Then send the required NSAlert “setter” messages to initialize the alert. Listing 1 gives an example of this.

   
   
   

   Listing 1  Creating and initializing the NSAlert object

   NSAlert *alert = [[[NSAlert alloc] init] autorelease];

   [alert addButtonWithTitle:@"OK"];

   [alert addButtonWithTitle:@"Cancel"];

   [alert setMessageText:@"Delete the record?"];

   [alert setInformativeText:@"Deleted records cannot be restored."];

   [alert setAlertStyle:NSWarningAlertStyle];

2. Invoke the beginSheetModalForWindow:modalDelegate:didEndSelector:contextInfo: method on the NSAlert object (Listing 2). This displays the sheet attached to the specified window.

   
   
   

   Listing 2  Displaying the alert sheet

   [alert beginSheetModalForWindow:[searchField window] modalDelegate:self didEndSelector:@selector(alertDidEnd:returnCode:contextInfo:) contextInfo:nil];

   The modal-delegate parameter must be an object that implements a method with the following signature:

   - (void)alertDidEnd:(NSAlert *)alert returnCode:(NSInteger)returnCode

   contextInfo:(void *)contextInfo;

   The NSAlert object invokes this method when the user clicks a button on the alert sheet to indicate their choice (which consequently dismisses the sheet). The modal delegate is not the recipient of any other delegation messages; it is the delegate only for the current modal session. The context-info parameter is for any data you wish to pass to the modal delegate. Instead of autoreleasing the NSAlert object when you create it, you may release the object in this method, if you wish.

3. Implement the modal-delegate method to identify the user’s choice and proceed accordingly (Listing 3).

   
   
   

   Listing 3  Interpreting the result in the modal delegate method

   - (void)alertDidEnd:(NSAlert *)alert returnCode:(NSInteger)returnCode contextInfo:(void *)contextInfo {

   if (returnCode == NSAlertFirstButtonReturn) {

   [self deleteRecord:currentRec];

   }

   }

   The return code is an enum constant identifying the button on the dialog that the user clicked. The first button added to the dialog (which, in left-to-right scripts, is the one closest to the right edge) is identified by NSAlertFirstButtonReturn. The second button that is added appears just to the left of the first and is identified by NSAlertSecondButtonReturn —and so forth for the third button.

As a convenience for compatibility with the older functional API (see Using the Functional API), you can create NSAlert objects with the class factory method alertWithMessageText:defaultButton:alternateButton:otherButton:informativeTextWithFormat:. This method allows you to retain the earlier constants used to identify the button clicked. Here is an example of how you might invoke this method (with the previous example in mind):

NSAlert *alert = [NSAlert alertWithMessageText:@"Delete the record?"

    defaultButton:@"OK" alternateButton:@"Cancel" otherButton:nil

    informativeTextWithFormat:@"Deleted records cannot be restored."];

Using the Functional API

The application assumed for this example is a table of expense report entries similar to a spreadsheet. The deleteSelectedRows: method is sent when the user tries to delete selected rows in the expense report. deleteSelectedRows: asks the user’s permission to delete the rows by displaying an alert sheet using the NSBeginAlertSheet function.

NSBeginAlertSheet has a fairly long list of parameters, but the function is not difficult to use. Here is a summary of the parameters:

title

The main text of the alert, which appears in the emphasized system font.

defaultButton

The label for the sheet’s default button; the button label should correspond to the action that will result from pressing the button–for example, “Save,” “Erase,” or “Delete”.

alternateButton

The label for the sheet’s alternate button. If you pass nil, only the defaultButton is displayed.

otherButton

The label for the sheet’s other button. If you pass nil, only the defaultButton and alternateButton are displayed.

documentWindow

A reference to the NSWindow the sheet is attached to.

modalDelegate

A reference to the object acting as the sheet’s delegate.

didEndSelector

A selector for a method implemented by modalDelegate. This method is sent when the modal session is ended, but before the sheet is dismissed. If you don’t need this capability, pass NULL.

didDismissSelector

A selector for a method implemented by modalDelegate. This method is sent after the sheet is dismissed in the event your application might need to perform additional processing. If you don’t need this capability, pass NULL.

contextInfo

Additional information you can define to pass to modalDelegate as a parameter of didEndSelector and didDismissSelector.

message

Optional additional text that appears in the sheet. The text appears in the small system font. This string can contain printf-style escape sequences.

optionalParameters

The printf-style parameters used to format message.

So, the implementation of deleteSelectedRows: would simply look as shown in Listing 4.

Listing 4  The deleteSelectedRows: method implemented to present a sheet with two buttons

- (BOOL)deleteSelectedRows: (NSWindow *)sender

{

    NSBeginAlertSheet(

        @"Do you really want to delete the selected rows?",

                                // sheet message

        @"Delete",              // default button label

        nil,                    // no third button

        @"Cancel",              // other button label

        sender,                 // window sheet is attached to

        self,                   // we’ll be our own delegate

        @selector(sheetDidEndShouldDelete:returnCode:contextInfo:),

                                // did-end selector

        NULL,                   // no need for did-dismiss selector

        sender,                 // context info

        @"There is no undo for this operation.");

                                // additional text

// We don’t know if the rows should be deleted until the user responds,

// so don’t.

    return NO;

}

When the user attempts to delete the selected expenses, the sheet shown in Figure 1 drops down from the window title bar.

The implementation of the did-end selector sheetDidEndShouldDelete:returnCode:contextInfo:, sent when the user clicks a button is as follows:

- (void)sheetDidEndShouldDelete: (NSWindow *)sheet

        returnCode: (NSInteger)returnCode

        contextInfo: (void *)contextInfo

{

    if (returnCode == NSAlertDefaultReturn)

    // delete selected rows here

}

If the user clicks the Cancel button, the value of returnCode is NSAlertOtherReturn. If a third button were provided, its return value would be NSAlertAlternateReturn.