How do I make my app expand/collapse from/to a Finder icon?

Question

You know how sometimes when you close a Finder window or document, it shrinks toward its representation in Finder. I want my application to be able to do this, too. Is there an API for this? I can't find any.

Answer 1

Executive summary: Use the NSDocument system if you want this behavior.

Details:

It looks like you're using TextEdit in your GIF. As it happens, Apple publishes the source code for TextEdit as sample code. So we can look and see if it does anything special to make this happen.

I couldn't find anything in the TextEdit source code. I poked around for a while and set some breakpoints but didn't find any evidence that TextEdit does this “manually”.

I discovered that if you open the file using File > Open (instead of double-clicking the file in the Finder), you do not get the animated closing window, even if the file is visible in the Finder.

But if you open the file using File > Open, then (without closing that window) double-click the file in the Finder, then you do get the animated closing window.

So I poked around a bit more, setting breakpoints and looking at disassembler listings, and I found what I think is the important bits, in -[NSWindow _close]. It goes basically like this:

- (void)_close {
    if (!_wFlags.windowDying) { return };
    if (_auxiliaryStorage->_auxWFlags.windowClosed) { return; }

    void (^actuallyCloseMyself)() = ^{ ... code to actually close the window ... };

    NSWindowController *controller = self.windowController;
    if (![controller respondsToSelector:@selector(document)]) { goto noCloser; }
    NSDocument *document = controller.document;
    if (![document respondsToSelector:@selector(fileURL)]) { goto noCloser; }
    QLSeamlessDocumentCloser *closer = [[NSDocumentController _seamlessDocumentCloserClass] seamlessDocumentCloserForURL:document.fileURL];
    if (closer == nil) { goto noCloser; }
    CGRect frame = NSRectZero;
    [closer closeWindow:self contentFrame:&frame withBlock:actuallyCloseMyself];
    goto done;

noCloser:
    actuallyCloseMyself();

done:
    _auxiliaryStorage->_auxWFlags.wantsHideOnDeactivate = YES;
}

So basically, if your window is attached to an NSWindowController, and the controller has an NSDocument, then AppKit will try to set up a “seamless close” using a QLSeamlessDocumentCloser. The QL prefix means it's part of QuickLook (the class is in fact found in the QuickLookUI framework, which is part of the Quartz framework).

I guess what happens is, when you open a file in the Finder, the Finder tells the QuickLook system (probably the quicklookd process) where on the screen it is displaying the icon for the file. When the closer is called (in TextEdit), if QuickLook has a frame to close to, it animates the window down to that frame before actually closing the window. If you didn't open the file via the Finder, QuickLook doesn't have a frame to animate to, so it presumably just calls the actuallyCloseMyself block immediately.