Hi Kyle. I don't believe there's a distinction here between "high level" and "low level" API. Iit's just a simple distinction between being done with the window and not being done with the window. When your app is permanently done with a window and will never display it again, you call -close, whereas if your app may display the window again, you call -orderOut:.
As for why there are two methods, -close is closely tied with the NSDocument architecture. It's no coincidence that NSWindow, NSWindowController, and NSDocument all have -close methods: http://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Documents/Concepts/WindowClosingBehav.html#//apple_ref/doc/uid/20000027-BBCBEIEJ I believe that the main purpose not only of -isReleasedWhenClosed but also NSWindowWillCloseNotification is to handle memory management and/or clean up when you're permanently done with a window. Indeed, the link above explains how you would use NSWindowWillCloseNotification for exactly that purpose. The method -orderOut: has no such side effects, because it's meant for temporarily removing a window from the screen, not getting rid of the window altogether. It's true that if you don't release either the window or the window controller when the window closes, then -close is pretty much equivalent to -orderOut:, but I don't think that's how the designers intended people to use the API. -Jeff On May 17, 2011, at 7:12 PM, Kyle Sluder wrote: > This seems like it should be such a fundamentally obvious difference, > but I've been quite puzzled about it ever since I first started > working with Cocoa: when is it more appropriate to call -[NSWindow > orderOut:] than -[NSWindow performClose:] (or just plain -close)? > > At first glance, it appears that -orderOut: is in the "window list > management" portion of the API, while -performClose:/-close are in the > "window existence management" portion. In other words, -orderOut: > seems to operate at a lower level than -close, as -close calls > -orderOut: (or the moral equivalent). > > So my gut intuition is that a reusable panel should be hidden with > -close, and set to not release when closed, so that it may be recalled > later. > > But then the actual framework has to go mess with this understanding. > It is apparent that NSColorWell calls -orderOut: on the shared color > panel, and in general there's tons of code out there that calls > -orderOut: to dismiss shared panels. Not to mention the method is an > IBAction, so it's obviously designed to be called from higher-level > code. > > The documentation is woefully ambiguous: > http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/WinPanel/Tasks/OpeningClosingWindows.html > > It feels like there are two overlapping entry points in the API: the > high level path (-close) that calls into the lower-level path > (-orderOut:), but that the lower-level path has gained acceptance as a > separate entry point since it implements most of the side effects seen > in the high level path. > > Is this redundancy an artifact of a time before NSWindowController, > when one-shot windows and releaseWhenClosed were far more commonplace > than they are today? If so, is there any hope for a restructuring of > the API in the future? Or does the distinction still exist as an > opportunity for the framework client to maintain a distinction between > "hiding" and "closing", even where the line is blurry, like in an > inspector or other reusable panel? > > And in the meantime, can someone enlighten me as to why I would ever > choose to call -orderOut: instead of -close on a properly-configured > reusable panel? _______________________________________________ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
