The Too Long, Didn't Read version:
Displaying a NSWindow, one that's lazily loaded from its own nib file, as a sheet doesn't have a any method for notifying observers that its about to be displayed, and therefore its difficult to reset the sheet UI on the second and later displays. Therefore, use this NSWindow subclass as your controller to re-set the UI right before the window will display as a sheet.
---
The long version wherein I lead the reader, step by step, through the problem and the solution to lazily-loaded, re-usable NSWindow objects displayed as a sheet:
In many examples of using custom NSWindow object displays as a sheet in a Cocoa application, found both on the web and in print, the author has placed the NSWindow object that will be used as a sheet inside in the .nib file of the window that the sheet will be attached to. This works fine if the sheet is guaranteed to be displayed to the user. On the other hand if you can't guarantee that the user will see the sheet, as you frequently cannot with a sheet, including the sheet in the nib file violates the guideline of "For a window or menu that is used only occasionally, store it in a separate nib file. By storing it in a separate nib file, you load the resource into memory only if it is actually used."
As a tangential discussion before diving into the main point, everytime you load a resource from a nib file all objects contained within the file, with the exception of the 'File's Owner', 'First Responder' and 'Application' objects since these are proxy objects, are unarchived and have their connections (both IBAction and IBOutlets) set up. Therefore, even if you don't use a particular resource contained with in the nib, such as in the case where the sheet is never presented to the user, the program has wasted both computation time and memory loading all the unused objects anyway. The more you can get away with not loading from your nib files, the faster your program will launch and the more memory efficient it will be while running. As such, the best way to handle NSWindow objects that may not be displayed to the user is to move them into their own nib file and only load them from the nib file when, and if, they need to be displayed to the user. For a more complete run down of the ins and outs of nib files please read through Apple's Resource Programming Guide.
So, in the case of a custom sheet, since we don't want to waste processing time and system memory until we need it, the best way to handle this is as follows. I'm purposefully omitting the corresponding .h files for this example since they're rather trivial. The only important part is that both MainWindowController and SheetController are both subclasses of NSWindowController:
MainWindowController.m
- (IBAction
)displaySheet
:(id)sender
{ SheetController
* sheetController
= [[SheetController alloc
] init
];
[NSApp beginSheet
:[sheetController window
] modalForWindow
:[self window
] modalDelegate
:self
didEndSelector
:@selector(sheetDidEnd
:returnCode
:contextInfo
:) contextInfo
:sheetController
];
} - (void)sheetDidEnd
:(NSAlert*)alert returnCode
:(NSInteger
)returnCode
contextInfo
:(void*)contextInfo
{ // do something with the user input to the sheet here SheetController
* sheetController
= contextInfo;
[sheetController release
];
}
SheetController.m
- (id)init {
self = [super initWithWindowNibName:@"someSheet"];
return self;
}
- (IBAction)dimissSheet:(id)sender {
[NSApp endSheet:[self window] returnCode:NSOKButton];
[[self window] orderOut:self];
}
This is just sample code, with just enough to show how displaying a sheet would work. Obviously it will work, but there's a subtle error in here that's easy to miss for new programmers. Everytime [[SheetController alloc] init] is called in the main window controller, the contents of the nib containing the sheet is opened, unpacked, and hydrated. Even though we're properly lazily loading the objects in the nib file, we've committed another error. We're now incurring the nib loading everytime the sheet displays. It would be better if we could unpack this information from the nib only once, and reuse the sheet NSWindow object every time and therefore we only incur the cost of instantiation the first time a user needs the sheet.
Easy enough, in theory (you'll see why this turns out to be harder than it looks in a second), and with that change it looks something like this:
MainWindowController.h
@interface MainWindowController
: NSWindowController { SheetController
* sheetController;
} ...
@end
MainWindowController.m
- (IBAction
)displaySheet
:(id)sender
{ if (sheetController
== nil) { sheetController
= [[SheetController alloc
] init
];
} [NSApp beginSheet
:[sheetController window
] modalForWindow
:[self window
] modalDelegate
:self
didEndSelector
:@selector(sheetDidEnd
:returnCode
:contextInfo
:) contextInfo
:sheetController
];
} - (void)sheetDidEnd
:(NSAlert*)alert returnCode
:(NSInteger
)returnCode
contextInfo
:(void*)contextInfo
{ // do something with the user input to the sheet here }
SheetController.m
- (id)init {
self = [super initWithWindowNibName:@"someSheet"];
return self;
}
- (IBAction)dimissSheet:(id)sender {
[NSApp endSheet:[self window] returnCode:NSOKButton];
[[self window] orderOut:self];
}
Now, we're creating the sheet a single time, which fixes the problem of loading the resources from the nib every time you display the sheet, but introduces a new problem (one that's hard to see from the example code without running a full application that implements this code). The problem is that because we're using the exact same NSWindow object over and over, if the sheet contains UI elements that the user can change (NSTextField, NSSlider, NSPopupButton, etc.) then those UI elements will be displayed as the user left them from the first time they interacted with the sheet. Sometimes this is the desired behavior, but in the event that its not, you have a problem.
Normally in the case where you want to re-use a window over and over and want to reset its UI every time its presented to the user, you can override the - (IBAction)showWindow:(id)sender method in the NSWindowController. Unfortunately for a NSWindow displayed as a sheet, the showWindow: method is not invoked by [NSApp beginSheet:...] and therefore your NSWindowController subclass isn't notified that the window is about to be displayed. This lack of notification just prior to the window showing on screen as a sheet is the heart of the problem. As a quick rundown of the methods you might think work but don't:
- When the sheet is loaded, it invokes
windowDidLoad: on its controller, but this only happens the first time its loaded from the nib and is never invoked again (since we're re-using the sheet and only loading it from the nib a single time), so it can't be used to reset the UI for the second display of the sheet.
- The NSWindow that will have a sheet attached to it notifies its delegate that its about to display a sheet through the
willDisplaySheet:(NSNotification*) method, but the notification contains a nil userInfo dictionary so it doesn't contain a pointer to the sheet its about to display
- You might think that when a window's delegate receives a
willDisplaySheet: notification the delegate could invoke the attachedSheet method on the window that's about to display a sheet. Unfortunately, the NSWindow's attachedSheet method returns nil at this point since the sheet isn't yet attached.
- You could override
[controller window] method on the NSWindowController for the sheet in order to reset the UI before returning the window object. This partially works since you'll reset the UI as part of the [NSApp beginSheet:[sheetController window] ...] invocation, but it also means you lose access to what the user did on the other side since dismissing the sheet through [NSApp endSheet:[self window] ...] also resets the UI.
Since the last bullet point is half usable, it turns out that with the right tweaks, we can avoid restting the UI while dismissing the sheet. I now present the DESSheetController, which you can use in your own Xcode project to fix this issue:
DESSheetController.h
// // DESSheetController.m // // Created by Peter Nix (pnix@digitalenginesoftware.com) // #import <Cocoa/Cocoa.h> /*!
@class DESSheetController
@abstract An abstract super class to use instead of NSWindowController to
assist in using sheets.
@discussion Using an NSWindow controller loaded from its own nib as a sheet
(a distinct nib from the window its going to attach to) doesn't have a good
notification to its NSWindowController or delegate that its about to display.
Therefore, it is very difficult to reset the UI to a default state when re-displaying
the sheet to the user. This class provides the necessary overrides and callbacks
to help reset the UI to a default state when reusing the same NSWindow
object as a sheet.
@updated 2010-10-13
*/ @interface DESSheetController
: NSWindowController { } /*!
@abstract dismissSheet: provides a way of dismissing the sheet without losing
the information contained in the UI elements the user can interact with.
@discussion Based on the override of the window method (see the implementation
file) if you call [self window] as part of the call to dismiss the sheet, you will
reset the UI on the sheet before you query for this information in your modal
delegate's selector callback. Therefore, the contract for overriding this class
for a custom sheet controller is call this method when dismissing the sheet
in order to preserve the UI state.
@param returnCode the integer indicating the status that the sheet ended with.
This parameter will be passed onto NSApp when sending the sheet out and in
turn gets passed to the modal delegate's callback selector.
*/ - (void)dismissSheet
:(NSInteger
)returnCode;
/*!
@abstract This is the method that needs to be overriden in your custom subclass
in order to reset the UI when redisplaying the sheet.
@discussion This method is invoked in the middle of returning the window from
your controller to the NSApp instance to begin a sheet. Therefore this method
is invoked at (literally) the last possible moment, meaning that all the UI for
the sheet has been properly hydrated from the nib, and is just about to be
displayed as a sheet. This method is empty in this class, and is designed to be
overridden by a custom subclass in order to perform any UI clean up in order
to get the sheet into a reset/clean state for display to the user.
*/ - (void)hydrateView;
@end
DESSheetController.m
#import "DESSheetController.h" @implementation DESSheetController
#pragma mark inherited methods - (NSWindow*)window
{ NSWindow* window
= [super window
];
[self hydrateView
];
return window;
} #pragma mark private methods - (void)hydrateView
{ // do nothing by design, overridden by sub-classes } - (void)dismissSheet
:(NSInteger
)returnCode
{ // note the use of super instead of self in order to bypass the sheet reset code // via the hydrateView method [NSApp endSheet
:[super window
] returnCode
:returnCode
];
[[super window
] orderOut
:self
];
} @end
So, now for a bit of explanation. The point is to use this class as your sheet controller's superclass instead of NSWindowController. By subclassing DESSheetController, all you have to do is implement -(void)hydrateView within your subclass and use that method to re-initialize the UI everytime the sheet is displayed. On the outgoing side, the contract is to invoke the - (void)dismissSheet:(NSInteger)returnCode method instead of invoking [NSApp endSheet:] directly in your subclass. The dismissSheet: method calls [super window] instead of [self window] and therefore avoids resetting the UI before the modal delegate can query the sheet for information.
Now, you can safely re-use a single NSWindow as a custom sheet for user interaction over and over again, and still stick to lazy initialization and avoid multiple nib loading.
