What’s the difference between presentedWindowStyle(_:) and windowStyle(_:)?

Well, one does something, the other doesn’t, basically.

I tried using the former, and observed that it never has any effect. I filed FB14892608 about it, a month ago. While the long delay isn’t great, the response I got today was actually pretty helpful:

We’re sorry you ran into trouble with that API.

To adjust the style of a window group’s windows, you have a couple of options. If all of the windows in the group should have the same style, then using the windowStyle() scene modifier is what you want:

struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .windowStyle(.hiddenTitleBar)
    }
}

If you need to adjust the style on an individual basis using state for that window, there are also some related view modifiers:
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .toolbar(removing: .title)
                .toolbarBackgroundVisibility(.hidden, for: .windowToolbar)
        }
    }
}

A simple apology followed by clear and specific instructions on how to actually achieve what I wanted. I genuinely applaud Apple – or perhaps I should more specifically thank the individual(s) within DTS that actually provided this response. Either way, it was a very pleasant surprise.

Now, it still leaves unanswered the question of what presentedWindowStyle(_:) is supposed to be for, and in what situations it actually does anything. So not a perfect reply, per se, but really the proper solution for that is either:

1. Fix the API to not have such confusingly similar modifiers.
2. Improve the documentation to:
   • Explicitly point out the other, similarly-named modifier.
   • Distinguish them.

Currently the documentation is just:

Versus:

The latter might technically convey something important here, in the created by interacting with this view part, but so much in SwiftUI is modifiers stuck haphazardly in weird and arbitrary places, that I’m been conditioned to ignore the fact that I’m often applying modifiers to views that don’t actually affect those views. And for all I know in SwiftUI parlance views do “create” and/or “interact” with their parent windows (a lot about SwiftUI is backwards, part of its nature as a declarative API).

Especially if that’s the first candidate API you stumble across, when searching for a way to style a window, it’s very easy to presume it’s the right API. Why would there be multiple APIs for styling the window; why would you continue searching after finding one?

Similarly, the presentedWindowStyle(_:) variant is the only one that appears in Xcode’s auto-complete if you try to add the modifier to your main view, which is both where you sometimes have to add window-level modifiers and also just a really easy mistake to make (instead of adding the modifier to the WindowGroup, one indentation level up).

Lastly, it doesn’t help that I can’t find any situation in which presentedWindowStyle(_:) has any effect, even knowing it’s not intended to style the parent window. One might assume it’s somehow related to sheets or somesuch, but apparently not? Presumably I’m overlooking some use-case – or maybe it doesn’t actually do anything on macOS, only iDevices? I welcome clues or tips.

If any view in the [active] window contains a Toggle – even one that’s disabled or hidden – then Continuity Camera (re. ImportFromDevicesCommands and importableFromServices) doesn’t work; all the submenu items under “Import from iPhone or iPad” are disabled.

I don’t know if this is truly specific to Toggle, that’s just the example case I happen to have isolated [first?].

What’s really weird is that once a Toggle has ever been displayed, even if you subsequently remove it from the view hierarchy entirely the “Import from iPhone or iPad” submenu items all remain disabled.

import SwiftUI

@main
struct Example: App {
    @State var breakImportFromiDevice = true
    @State var text = ""

    var body: some Scene {
        WindowGroup {
            VStack {
                TextField("Input", text: $text) // Doesn't break anything.

                if breakImportFromiDevice {
                    Toggle("Break import from iDevice", isOn: $breakImportFromiDevice)
                }
            }
            .importableFromServices(action: { (images: [NSImage]) -> Bool in
                print("Load image!")
                return true
            })
        }.commands {
            ImportFromDevicesCommands()
        }
    }
}

There are some circumstances in which this gets “unbroken” during interactions with other views and so forth, which is 100% reproducible in my real app but I have no idea what the reason is. The steps involved in my real app are kinda ridiculous (and not in any way remotely a viable workaround) and make absolutely no sense – it only “unbreaks” when a specific view is in a specific weird state (itself kind of the result of a bug, albeit a benign one). And that weird state is merely whether it’s displaying one image or another – which as far as SwiftUI is concerned is not even a difference in view state, since I’m just swapping NSImages under the cover.

I figured it must be something to do with view focus, but after much experimentation I believe I can conclusively rule that out. No matter which view has focus, or how focus is configured, or which views are even focusable at all, the problem persists. Likewise for window focus and key state. And, [accessability-]focusable views other than Toggle – e.g. TextField – don’t cause any issues.

Frankly it’s baffling, and a mite infuriating. I can’t even conceive of how SwiftUI can be so incredibly broken regarding such basic functionality, and the apparent interaction of GUI elements that have absolutely no business together.

Tangentially, a few things I’ve noticed about this Continuity Camera feature:

• “Add Sketch” doesn’t do anything. Unlike the other options, which open the camera app on the target iDevice, it has no effect. 🤷‍♂️
• Within the Finder, you can right-click empty whitespace within a folder, and the contextual menu has this “Import from iPhone or iPad” option at the bottom. That’s pretty handy – until now I’d been doing it the “hard” way by taking a photo on my iPhone and AirDropping it across to my Mac.
  
  I’d never noticed that feature prior to debugging this problem (I wanted to confirm that multiple other apps worked just fine; that it wasn’t an issue with Continuity Camera system-wide).
• TextEdit has the same feature but tweaks the wording to “Insert…” rather than “Import…”, which I thought is both a nice touch and frustratingly not something you can do in your own apps (at least, not in SwiftUI). 😕

NSPasteboard mutates itself simultaneously from the main thread and the global concurrent Dispatch pool, w.r.t. to its internal type cache. This is surprisingly trivial to reproduce (sample code below) by just dropping, e.g. a file promise (such as by opening a PNG in Preview, revealing the thumbnails sidebar, and then dragging the thumbnail onto the sample project’s window).

import SwiftUI

struct ContentView: View {
    var body: some View {
        Rectangle().onDrop(of: NSImage.imageTypes, isTargeted: nil) { _ in
            let pb = NSPasteboard(name: .drag)

            _ = pb.pasteboardItems // Seems to be necessary for the crash.

            _ = NSImage.imageTypes // Not strictly necessary for the crash, but seems to make it more likely. 🤷‍♂️

            return true
        }
    }
}

Judging from the callstack that runs in the concurrent pool, this is specific to file promises (and that seems to match my experience – it only crashes for some test cases, all of which involve file promises being present in the drag pasteboard at the time of the drop).

Since this bug causes semi-random memory corruption, it manifests in a large number of ways – not all of which are all that helpful. But at least one case I’ve seen a few times is helpful, as it clearly shows the offending internal NSPasteboard code running concurrently with itself, e.g.:

Main queue / thread:
#0	0x00007ff80108dab5 in _platform_bzero$VARIANT$Haswell ()
#1	0x000000010df8774d in GuardMalloc_mallocInternal ()
#2	0x00007ff90792542f in stack_logging_lite_malloc ()
#3	0x00007ff800ea8733 in _malloc_zone_malloc_instrumented_or_legacy ()
#4	0x00007ff800f39a72 in _vasprintf ()
#5	0x00007ff800f16922 in asprintf ()
#6	0x00007ff80125655a in -[NSObject(NSObject) __dealloc_zombie] ()
#7	0x00007ff8020e039a in -[NSConcreteMapTable dealloc] ()
#8	0x00007ff804876983 in -[NSPasteboard _updateTypeCacheIfNeeded] ()
#9	0x00007ff8048763df in -[NSPasteboard _typesAtIndex:combinesItems:] ()
#10	0x00007ff804aad148 in NSCoreDragReceiveMessageProc ()
#11	0x00007ff807517b1a in CallReceiveMessageCollectionWithMessage ()
#12	0x00007ff8075124fa in DoMultipartDropMessage ()
#13	0x00007ff8075122ce in DoDropMessage ()
#14	0x00007ff8075159a9 in CoreDragMessageHandler ()
#15	0x00007ff8011d776b in __CFMessagePortPerform ()
#16	0x00007ff80113e5b7 in __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE1_PERFORM_FUNCTION__ ()
#17	0x00007ff80113e4ee in __CFRunLoopDoSource1 ()
#18	0x00007ff80113d166 in __CFRunLoopRun ()
#19	0x00007ff80113c112 in CFRunLoopRunSpecific ()
#20	0x00007ff80bb55a09 in RunCurrentEventLoopInMode ()
#21	0x00007ff80bb55646 in ReceiveNextEventCommon ()
#22	0x00007ff80bb55561 in _BlockUntilNextEventMatchingListInModeWithFilter ()
#23	0x00007ff8047acc61 in _DPSNextEvent ()
#24	0x00007ff8050c0dc0 in -[NSApplication(NSEventRouting) _nextEventMatchingEventMask:untilDate:inMode:dequeue:] ()
#25	0x00007ff80479e075 in -[NSApplication run] ()
#26	0x00007ff804771ff3 in NSApplicationMain ()
#27	0x00007ff90dc24557 in ___lldb_unnamed_symbol57096 ()
#28	0x00007ff90e31fe64 in ___lldb_unnamed_symbol104448 ()
#29	0x00007ff90e6e63ff in static SwiftUI.App.main() -> () ()
#30	0x000000010dfa5cce in static NSPasteboardItem_CrashApp.$main() ()
#31	0x000000010dfa5d69 in main at /Users/SadPanda/Documents/NSPasteboardItem Crash/NSPasteboardItem Crash/NSPasteboardItem_CrashApp.swift:11
#32	0x00007ff800cd5366 in start ()

Dispatch concurrent queue (default QoS):
#0	0x00007ff80111b45c in -[__NSSetM addObject:] ()
#1	0x00007ff80487692e in -[NSPasteboard _updateTypeCacheIfNeeded] ()
#2	0x00007ff8048763df in -[NSPasteboard _typesAtIndex:combinesItems:] ()
#3	0x00007ff804aa9597 in -[NSPasteboard _canRequestDataForType:index:usesPboardTypes:combinesItems:] ()
#4	0x00007ff804fdd161 in -[NSPasteboard _dataForType:index:usesPboardTypes:combinesItems:securityScoped:] ()
#5	0x00007ff804aa7c4b in -[NSPasteboardItem dataForType:] ()
#6	0x00007ff8055804af in -[NSFilePromiseReceiver receivePromisedFilesAtDestination:options:operationQueue:reader:] ()
#7	0x00007ff90e787b51 in ___lldb_unnamed_symbol131674 ()
#8	0x00007ff90e9bc340 in ___lldb_unnamed_symbol148147 ()
#9	0x00007ff8020d00ba in __NSBLOCKOPERATION_IS_CALLING_OUT_TO_A_BLOCK__ ()
#10	0x00007ff8020cffb8 in -[NSBlockOperation main] ()
#11	0x00007ff8020cff4b in __NSOPERATION_IS_INVOKING_MAIN__ ()
#12	0x00007ff8020cf1ec in -[NSOperation start] ()
#13	0x00007ff8020cef0d in __NSOPERATIONQUEUE_IS_STARTING_AN_OPERATION__ ()
#14	0x00007ff8020cedde in __NSOQSchedule_f ()
#15	0x000000010e68ce7d in _dispatch_block_async_invoke2 ()
#16	0x000000010e67ca7b in _dispatch_client_callout ()
#17	0x000000010e67fa09 in _dispatch_continuation_pop ()
#18	0x000000010e67eae8 in _dispatch_async_redirect_invoke ()
#19	0x000000010e6906a9 in _dispatch_root_queue_drain ()
#20	0x000000010e6911ba in _dispatch_worker_thread2 ()
#21	0x000000010dfb832f in _pthread_wqthread ()
#22	0x000000010dfbebeb in start_wqthread ()

There doesn’t appear to be any workaround (short of not supporting drops at all!).

The more complicated the drop handler the more likely it is to promptly crash upon drop – in my real code with a non-trivial handler, it’s virtually guaranteed to crash on the second drop containing a file promise, while in the vastly reduced sample code (above) it can take dozens of drops before it finally crashes outright.

I have not directly tested whether this NSPasteboard bug occurs in the absence of SwiftUI, so I don’t strictly know if the root cause is in AppKit or SwiftUI. However, since most SwiftUI apps don’t support drag-and-drop, but plenty of AppKit ones do and manage to not crash when given the exact same test cases, I do strongly suspect SwiftUI is causing this somehow.

Follow-up (September 12th, 2024)

I actually received a response from Apple, from a real human (or at least a convincing AI). Ultimately their response didn’t help as it contained some mistakes, but I’m hopeful there’ll be more follow-up and a productive conclusion. And in the interim, they did assert a few things which are important to know, and are not otherwise documented by Apple:

• SwiftUI’s onDrop(of:isTargeted:perform:) method makes no claims or promises as to what thread / queue it executes the closure on, and in fact according to the anonymous Apple engineer it never executes the closure on the main thread.
  
  Now, while that may be the intent, the reality of that is wrong – in my experience it always executes the closure on the main thread (which makes a lot of sense to me as drag-and-drop event handling in AppKit has always been on the main thread in practice).
  
  Nonetheless, Apple says one cannot rely on the current behaviour and should in fact assume it never executes on the main thread (though in practice that means you have to check, not assume, since if you blindly do something like DispatchQueue.main.sync { … } in your drop handler your code will deadlock, today).
• NSPasteboard is not safe to use outside the main thread / queue.
  
  This isn’t documented anywhere public – not in NSPasteboard‘s documentation itself, nor the ancient Application Kit Framework Thread Safety documentation.
  
  I wouldn’t be surprised if it’s broadly true, as the AppKit APIs involving it always seemed main-thread centric anyway (all the handlers and delegate methods involving pasteboards are invoked on the main thread, in my experience). And it’s generally best to assume everything in AppKit is main-thread-only unless it’s explicitly documented otherwise.
  
  However, it’s important to note that Apple’s own code doesn’t follow this rule – e.g. NSFilePromiseReceiver, internally, uses NSPasteboard from the global concurrent queue.

Even though Apple’s initial response to this bug report hasn’t been all that fruitful, I do want to emphasise the fact that they did respond, which was a pleasant surprise and very much appreciated.

A brief history of Contextual Menus

Contextual menus were introduced [to the Mac] in 1997 with Mac OS 8, with the new Contextual Menu Manager system extension and associated Contextual Menu Modules. See also the Mac OS 8 edition of the HIG (page 93).

Support varied a lot in the early days, though, and some user-interface conventions didn’t solidify until a few years later. e.g. SimpleText didn’t support contextual menus at all in Mac OS 8.0, and while 3rd party apps like BBEdit eventually did, it took longer still for now-standard items to become commonplace, like Cut / Copy / Paste.

Broadly-speaking, contextual menus have changed very little over the decades. At some point the app-specific commands were separated from the system-wide commands, the latter becoming relegated to the current “Services” submenu. And the specific menu items have of course evolved over time, but the basic idea has persisted: to provide app-specific or built-in commands followed by commands proffered by system-wide extensions.

It’s chuckle-worthy to remember that when Mac OS 8, with Contextual Menus, was introduced, Macs still had one-button mice. I don’t recall but assume it was possible to connect a mouse with multiple buttons, to a Mac, but remember that no Macs had USB at this time (that didn’t arrive until the iMac in August 1998, nearly a year later). Prior to USB, Macs used different I/O ports than PCs (ADB vs PS/2, for the most part), so there were a lot fewer mouse (and keyboard) options for Macs. Thus, contextual menus were originally – and to this day still also – invoked by control-clicking. You might have encountered the term “secondary-click[ing]”, which arose in that era to abstract over whether it was a physically distinct mouse button or just a modified left click¹.

It apparently wasn’t until the Mighty Mouse in 2005 that Apple actually shipped a multi-button mouse. (I say apparently because I don’t personally recall, and I had switched to 3rd party mice long before then anyway so I probably didn’t even notice at the time)

Are Services still relevant?

I assume that the Services submenu – whether through contextual menus or the app menu – is not used by most Mac users today, if only because the Mac user-base has expanded massively and most people barely leave their web browsers. I’ve heard Services derided or overlooked as a “power-user” or “niche” feature. Which is sad, because they can be very handy.

More importantly, some of your app’s users might rely heavily on Services as part of their personal workflow and choice, and it’s really not our place – as native Mac application developers – to tell them they shouldn’t use a standard system feature.

It’s frustrating for end-users to encounter applications which don’t support standard Mac features, like Services, and makes such applications stand out as non-native or otherwise broken.

It is sad that SwiftUI is in the general company of Electron and its ilk, here.

So how’s it done?

There’s probably at least two ways to do this, one of them being to manually insert the Services menu item into an otherwise vanilla SwiftUI menu. But I quickly ran into non-trivial challenges in pursuing that avenue, as you can’t just ask AppKit for the Services menu item, or its contents. Alas.

Ultimately I found it easier – and more in keeping with the grain – to instead just not use SwiftUI for contextual menus at all. But fortunately that doesn’t mean abandoning SwiftUI entirely, merely intermingling some AppKit into it.

The basic design is the standard AppKit sandwich²: an NSViewRepresentable containing an NSHostingView.

The first part is particularly easy, and just the usual annoying boilerplate:

struct ContextualMenuView<Content: View>: NSViewRepresentable {
    let viewContent: () -> Content
    let textProvider: @MainActor () -> String

    init(@ViewBuilder viewContent: @escaping () -> Content,
         text: @autoclosure @escaping @MainActor () -> String) {
        self.viewContent = viewContent
        self.textProvider = text
    }

    func updateNSView(_ nsView: ContextualMenuViewImplementation<Content>,
                      context: NSViewRepresentableContext<ContextualMenuView>) {
        nsView.rootView = self.viewContent()
        nsView.textProvider = self.textProvider
    }

    func makeNSView(context: Context) -> ContextualMenuViewImplementation<Content> {
        ContextualMenuViewImplementation(rootView: viewContent(),
                                         textProvider: textProvider)
    }

    func sizeThatFits(_ proposal: ProposedViewSize,
                      nsView: ContextualMenuViewImplementation<Content>,
                      context: Context) -> CGSize? {
        return nsView.fittingSize
    }
}

I’ve hard-coded it for text in this example, for simplicity, but you can adjust that to suite your needs.

For convenience it’s nice to add a view modifier for this too:

extension View {
    func contextualMenu(for textProvider: @autoclosure @MainActor () -> String) -> ContextualMenuView<Self> {
        ContextualMenuView(viewContent: { self },
                           text: textProvider)
    }
}

And now on to the real guts of all this, the custom NSView subclass that will define the contextual menu. Fortunately, NSView has very straightforward built-in support for contextual menus, so you don’t need to worry about mouse-event handling – you just provide it a non-nil NSMenu and it does the rest.

class ContextualMenuViewImplementation<Content: View>: NSHostingView<Content>,
                                                       NSServicesMenuRequestor {
    @MainActor fileprivate var textProvider: @MainActor () -> String

    @MainActor required init(rootView: Content,
                             text: @autoclosure @MainActor () -> String) {
        self.textProvider = text
        super.init(rootView: rootView)
    }
    
    // Mandated by NSHostingView, but not actually necessary for our purposes here.  But feel free to give this a real implementation, if that makes sense for your use and needs.
    @MainActor @objc required dynamic init?(coder aDecoder: NSCoder) {
        fatalError("init(coder:) has not been implemented for ContextualMenuView")
    }

    // As above.
    @MainActor required init(rootView: Content) {
        fatalError("init(rootView:) has not been implemented for ContextualMenuView")
    }

    @objc override func validRequestor(forSendType sendType: NSPasteboard.PasteboardType?,
                                       returnType: NSPasteboard.PasteboardType?) -> Any? {
        guard sendType == .string || sendType == .init("NSStringPboardType") else {
            return super.validRequestor(forSendType: sendType, returnType: returnType)
        }

        return self
    }

    @objc nonisolated func writeSelection(to pboard: NSPasteboard,
                                          types: [NSPasteboard.PasteboardType]) -> Bool {
        guard types.contains(.string) || types.contains(.init("NSStringPboardType")) else {
            return false
        }
        
        let text = if Thread.isMainThread {
            self.textProvider()
        } else {
            DispatchQueue.main.sync {
                self.textProvider()
            }
        }

        pboard.setString(text, forType: .string)
        return true
    }

    @objc override func menu(for event: NSEvent) -> NSMenu? {
        NSApplication.shared.registerServicesMenuSendTypes([.string, .init("NSStringPboardType")],
                                                           returnTypes: [])

        let menu = NSMenu()
        menu.allowsContextMenuPlugIns = true

        // Insert other menu items here.

        return menu
    }
}

The only real complexity is in the NSServicesMenuRequestor delegate method writeSelection(to:types:). Because it’s declared nonisolated by the NSServicesMenuRequestor protocol, you’re forced to assume it can be called in any isolation context; from any thread. Unfortunately, at runtime it’s sometimes – but not always! – called from the main thread. Swift doesn’t have an elegant way to say “run this synchronously on the main thread / actor” – if you naively call DispatchQueue.main.sync(…) and you’re already on the main queue, it crashes your application! So you must manually check for being on the main thread, and handle that specially. 😒

The other thing you might want to consider, not shown in the simple example above, is whether you want to support Services sending data back to your view. e.g. they might transform the text and return the new text to you, or generate / source text from somewhere else entirely for you. If you wish to support that, you need to populate the returnTypes argument to registerServicesMenuSendTypes(_:returnTypes:) and implement the readSelection(from:) delegate method.

How’s it done better?

The above works – and is the canonical way to do it. It results in the same plain Services submenu as you’ll see throughout Mac apps.

But that menu’s not great. It just dumps everything it a big amorphous list, with no delineation and merely alphabetical ordering.

Whereas if you look the Services submenu in the application menu:

…it is superior in many ways:

• There are more items.
• There’s a link to System Preferences / Settings to adjust which services are shown.
• There’s dividers in appropriate places, with subheadings, to help visually organise everything.
• App icons are shown to better visually distinguish each service.
• The grouping is somewhat alphabetical but with all services from a given app shown contiguously.

Some of the items shown aren’t actually context-specific – or at least, to no more detail than merely which application is targeted – but they’re intentionally relegated to the bottom, and could be handy anyway. e.g. if you can see any right-clickable area of any window of an application, you can quickly start profiling that application in Instruments.

It’s not hard, per se, to get the better menu. But it’s not documented, not officially supported, and has some broken edge cases. It is how many applications insert the Services menu into their menus (in fact it was the Electron source which helped me figure out how to do this in the first place), so it’s highly unlikely Apple will break it in the foreseeable future. Nonetheless, be warned.

The main edge case / bug that I’ve encountered is that this better Services submenu only works if the window is key. And there’s no way to force the window to be key (all of the AppKit APIs which seem specifically for that purpose flat-out do not work, such as makeKeyWindow). So you have to fall back to the lesser version of the Services menu in those cases. Which is basically whenever the view’s window is not the active window when the right-click occurs (or, whenever that macOS bug hits whereby the window is shown as if it’s the key window but actually isn’t 😤).

Anyway, with all that in mind and apparently not having dissuaded you, here’s the code to go in menu(for:):

menu.allowsContextMenuPlugIns = !(self.window?.isKeyWindow ?? false)

if !menu.allowsContextMenuPlugIns && !(self.window?.makeFirstResponder(self) ?? false) {
    print("Unable to make self the first responder - reverting to built-in Services submenu.")
    menu.allowsContextMenuPlugIns = true
}

// Add all your other items here.

if !menu.allowsContextMenuPlugIns {
    menu.addItem(NSMenuItem.separator())

    let services = NSMenuItem(title: "Services", action: nil, keyEquivalent: "")
    let serviceSubmenu = NSMenu()
    services.submenu = serviceSubmenu
    services.representedObject = textItem.provider
    NSApplication.shared.servicesMenu = serviceSubmenu
    menu.addItem(services)
}

Fortunately – and thanks to the deep elegance of AppKit’s design – that’s it! It otherwise uses all the same machinery as before (like writeSelection(to:returnType:)).

⚠️ macOS 14 Sonoma has a rendering bug when first opening the Services submenu within a given application session, as shown below. It’s not a big deal insofar as most of the items still work, and dismissing the menu and re-opening it fixes the rendering.

Bonuses

Adding a Copy menu item

Since the contextual menu is empty except for the default Services menu, you’ll probably want to add in some of the other options that are typically found in the contextual menu – Copy being perhaps the most prominent and often-used.

Fortunately, it’s trivial:

@MainActor @objc func doCopy(_ menuItem: NSMenuItem) {
    let pb = NSPasteboard.general
    pb.prepareForNewContents(with: nil)
    pb.setString(self.textProvider(), forType: .string)
}

// Then, in your `menu(for:)` method:
do {
    let copyMenuItem = NSMenuItem(title: "Copy", action: #selector(Self.doCopy(_:)), keyEquivalent: "")
    copyMenuItem.target = self
    copyMenuItem.isEnabled = true
    menu.addItem(copyMenuItem)
}

One obvious missing piece is localisation of the “Copy” label; left as an exercise for the reader.

Adding a Share menu item

It’s similarly simple to add a standard Share menu item:

@MainActor @objc func showSharePopup(_ menuItem: NSMenuItem) {
    let picker = NSSharingServicePicker(items: [self.textProvider()])
    picker.show(relativeTo: self.bounds, of: self, preferredEdge: .maxY)
}

// Then, in your `menu(for:)` method:
do {
    let picker = NSSharingServicePicker(items: ["🐞"])
    let pickerMenuItem = picker.standardShareMenuItem
    pickerMenuItem.target = self
    pickerMenuItem.action = #selector(Self.showSharePopup(_:))
    pickerMenuItem.isEnabled = true
    menu.addItem(pickerMenuItem)
}

This one benefits from using the standard, AppKit-provided menu item, so you don’t need to handle localising its label.

The 🐞 is there for two reasons:

1. You have to provide NSSharingServicePicker the nominal item(s) to share up front, in order to initialise it (and so it can tailor its display to the content). standardShareMenuItem should actually be a class member variable, not an instance member variable – a design flaw in AppKit.
   
   You don’t want to invoke the textProvider closure unless you really need to (it could be time-consuming to run, so you don’t want to run it unnecessarily nor while the user is trying to navigate the contextual menu lest it cause GUI hiccups). So an equivalent placeholder value – any other string, in this case – is better, and suffices.
2. I use the ladybug emoji so that it stands out if the value ever somehow gets shown to the user (it’s a bug, get it? 😄).

Adding a Look Up menu item

This one’s a little bit more iffy. If you think you genuinely have need of a Look Up item, consider whether you should be instead making the text selectable and simply utilising the built-in contextual menu support that selectable text views have in SwiftUI.

@MainActor @objc func lookUp(_ menuItem: NSMenuItem) {
    self.showDefinition(for: NSAttributedString(string: self.textProvider()),
                        at: NSPoint(x: CGFloat.infinity, y: CGFloat.infinity))
}

// Then, in your `menu(for:)` method:
do {
    let lookupItem = NSMenuItem(title: submenu == menu ? "Look Up “\(self.textProvider())”" : "Look Up",
                                action: #selector(Self.lookUp(_:)),
                                keyEquivalent: "")
    lookupItem.target = self
    lookupItem.isEnabled = true
    menu.addItem(lookupItem)
}

This doesn’t display perfectly. The use of infinities for the at argument causes it to draw a small yellow box at the top left of the view, layered underneath the contextual menu but usually still visible. That’s a hack for cases where you can’t determine where the text is, or the text being looked up doesn’t exactly match what’s shown in the view.

If you know the actual location of the selected text, you can specify that instead to get the yellow text drawn in that location. But beware: the text from textProvider must exactly match what’s rendered in the view, otherwise the yellow overlaid box – intended to look like a highlight effect – will look weird, because it [re]renders the text based on what textProvider returned. It also might not correctly match the font, in any case.

Thus why I caution against using the reinvention of this particular wheel.

1. Possibly borrowed from earlier computers that had multi-mouse-button support, such as some Unixes, but I suspect just coincidence. I vaguely recall that they were the philosophical antithesis of Apple w.r.t. mouse buttons, with some *nix GUIs requiring at least three mouse buttons for their basic function. I seem to recall some of them labelling the buttons primary, secondary, and tertiary. ↩︎
2. I doubt I came up with this metaphor – although it’s pretty obvious in any case – but it’s worth considering if it’s more than just a cute superficial analogy. AppKit forms the meaningful contents of the sandwich, providing its flavour, substance, and value, while SwiftUI serves only as the bread, there mainly just to convey the contents. 🤔 ↩︎

To make it invisible you need only set its opacity to zero or use the hidden modifier. But the view will still be laid out just the same, and take up space in the GUI.

If you want to actually hide the view, so that it disappears completely, you can either not emit the view at all (e.g. conditionalise its existence with if or switch) or you can replace it with EmptyView.

EmptyView is pretty marvellous in this respect. Notice how even though it’s a real view – an actual value that you emit from a view builder – layout collections (e.g. HStack) don’t “see” it – there’s no visible gap, from doubling up on the cell padding, like there would be if they simply treated EmptyViews like 0 wide ⨉ 0 high views.

You might ask, when would you actually need EmptyView? Wouldn’t you’d just use conditional code to hide a view, e.g.:

struct MyView: View {
    let model: Model?
    
    var body: some View {
        if let model {
            Text(model.text)
        }
    }
}

// Now you can just use MyView(model: someOptional),
// without having to unwrap it before every use.

The above is making use of the “ViewBuilder mode”, to implicitly yield zero or more views which are automagically aggregated into a TupleView (if you emit more than one), an optional view (if you dynamically emit zero or one), etc. That’s very convenient, in simple cases like that.

But, “ViewBuilder mode” comes with a lot of limitations, including:

• Compiler diagnostics are far inferior to regular Swift code.
• You cannot return early (i.e. use return statements) except by throwing an exception, which is not always semantically appropriate.
• You cannot have nested functions.
• You sometimes cannot use full Swift control flow syntax (e.g. switch statements).

Fortunately, you can opt out of “ViewBuilder mode” by simply using an explicit return statement, but then you have to follow the usual rules for opaque return types, i.e. that the value be of the same type for every return statement. You can use AnyView in concert with EmptyView to straighten the compiler’s knickers regarding the return type¹, e.g.:

struct MyView: View {
    let model: Model?
    
    var body: some View {
        guard let model else {
            return AnyView(EmptyView())
        }
        
        return AnyView(<actual view contents>)
    }
}

…or – if you don’t mind the return type being Optional, which SwiftUI itself doesn’t – you can use a partially opaque return type:

struct MyView: View {
    let model: Model?
    
    var body: Optional<some View> {
        guard let model else {
            return Body.none
        }
        
        return <actual view contents>
    }
}

Thanks to Dima Galimzianov for helping me figure out how to do that.

Note that in the trivial cases shown above there’s no particularly compelling reason to use these forms instead of the “ViewBuilder mode”, but you could hopefully imagine how, as the conditional logic gets more complicated, it becomes increasingly impractical to avoid using guard, or early returns otherwise.

In case you’re wondering, there’s no difference in show/hide behaviour either – it just works!

It’s possible that there’s some situations in which using EmptyView might cause animation issues, by confusing SwiftUI as to what the relationship is between view hierarchies over time, but I haven’t found that to be the case in practice. And if it ever does crop up, you can always just explicitly id your views.

EmptyView is one of those little sleeper features that seems irrelevant until you stumble upon a need for it, and then it’s really nice to have.

1. There’s technically another option: use a concrete return type instead. But, that’s usually impractical – SwiftUI uses opaque return types a lot, such as for virtually all view modifiers, which force you to use opaque return types in turn. And even when that isn’t an issue, good luck deducing the correct fully-qualified type name even for something as simple as a LabeledContent. ↩︎
2. Literally, “Fear, Uncertainty, and Doubt”. Used here in that face-value sense, not to suggest any malice on anyone’s part. ↩︎

FB13583826.

Is that it?

I know that’s not a very helpful in some sense, but I wasted days trying to figure out how to implement this very basic drag and drop functionality, in SwiftUI. From what I found online, I’m not the only person who’s struggled with this. So hopefully this post saves others from long and frustrating searches.

A big part of the difficulty in answering this simple question – does SwiftUI support this or not – is that a lot of documentation (first & third party) around SwiftUI’s APIs uses the word “promise” but not in the same way. They merely mean that the pasteboard data is populated on first access, not that it actually follows the file promise protocol.

Best alternative (other than ditching SwiftUI)

The closest you can get is to write data into some arbitrary location that you have to choose blindly (not having any idea where the actual destination is), and then rely on the receiving app to move or copy the file from there. It doesn’t matter, in this regard, whether you use the Transferable-based APIs or the NSItemProvider-based APIs.

view.onDrag {
    let provider = NSItemProvider()
    
    provider.registerDataRepresentation(for: UTType.fileURL) {
        do {
            let tmpDir = try FileManager.default.url(for: .itemReplacementDirectory,
                                                     in: .userDomainMask,
                                                     appropriateFor: URL.temporaryDirectory,
                                                     create: true)

            // You'll need to provide the `suggestedFileName` based on the particulars of your use-case.
            let file = tmpDir.appending(component: suggestedFileName)

            try bytes.write(to: file, options: .withoutOverwriting)

            $0(file.dataRepresentation, nil)
        } catch {
            $0(nil, error)
        }

        return nil
    }
    
    return provider
}

This makes it impossible to avoid unnecessary file copies, and requires you to keep the file around permanently, since you have no idea when the receiver is done with it.

e.g. if the Finder is the drop destination, you have no idea what volume the promised file was dropped on, so you don’t know which volume to create it on. If you guess wrong, the Finder is forced to copy the file. Not only does this confuse the user (by showing a copy badge on the mouse pointer) but it wastes time (in performing the copy) and the original file is left in place, requiring manual clean-up (which is impossible to do correctly because you have no idea when the receiving application is done with the temporary file – and the receiver might hold a reference to it permanently).

Understanding the SwiftUI drag & drop APIs

Tangentially, I found most documentation on SwiftUI’s drag & drop APIs – especially Apple’s – to be very poorly written, which is particularly frustrating in this case because the APIs are not intuitive in the slightest.

And most code / usage examples focus exclusively on trivial, disinteresting cases (e.g. dragging images around within a single window).

Only after I’d spend days reverse-engineering the APIs to figure out how they actually work and how they’re supposed to be used, did I stumble upon Dave Rahardja‘s All about Item Providers. It’s by far the best documentation I’ve found on drag & drop in SwiftUI. Note though that Dave also uses the word “promise” a lot even though he’s never actually talking about actual file promises.

Also, I found that the newer and ostensibly better Transferable-based API was harder to understand and harder to use than the NSItemProvider-based APIs. I recommend going straight to, and sticking with, the latter. Your code will be simpler and more reliable.

The following classes and functions are generally not thread-safe. In most cases, you can use these classes from any thread as long as you use them from only one thread at a time. Check the class documentation for additional details.

Apple’s Threading Programming Guide > Appendix A: Thread Safety Summary, subsection Application Kit Framework Thread Safety

What “in most cases” means is left to the reader’s imagination. Apple adds a little addendum for NSImage specifically:

One thread can create an NSImage object, draw to the image buffer, and pass it off to the main thread for drawing. The underlying image cache is shared among all threads. For more information about images and how caching works, see Cocoa Drawing Guide.

NSImage Restrictions

For a start, it’s talking only about creating an NSImage from scratch, not loading it from serialised form (e.g. a file, a pasteboard, etc). It doesn’t even deign to mention those other, much more common cases.

And even for that one mentioned use case, what does it mean, exactly? What “image cache” is it referring to?

I don’t have authoritative answers. The documentation is so infuriatingly vague that Apple could do basically anything to the implementation, between macOS updates, and claim to have broken no promises.

What I do have is some empirical data and the results of some reverse engineering (shout out to Hopper), from macOS 14.2 Sonoma.

NSImage 101

NSImages can represent a wide range of imagery. Most uses of them are probably for bitmap data (i.e. what you find in common image formats like WebP & AVIF), but NSImage also supports ‘raw’ images (e.g. Nikon NEF) as well as vector data (e.g. SVG & PDF). It also has a plug-in mechanism of sorts, so the supported image formats can be extended dynamically at runtime.

You can fetch the full list of supported types from NSImage.imageTypes – although it doesn’t distinguish between those it can read vs those it can write. Fortunately, sips --formats in Terminal gives you the same list with additional metadata. On my machine that list happens to be:

Supported Formats:
-------------------------------------------
com.adobe.pdf                pdf   Writable
com.adobe.photoshop-image    psd   Writable
com.adobe.raw-image          dng   
com.apple.atx                --    Writable
com.apple.icns               icns  Writable
com.apple.pict               pict  
com.canon.cr2-raw-image      cr2   
com.canon.cr3-raw-image      cr3   
com.canon.crw-raw-image      crw   
com.canon.tif-raw-image      tif   
com.compuserve.gif           gif   Writable
com.dxo.raw-image            dxo   
com.epson.raw-image          erf   
com.fuji.raw-image           raf   
com.hasselblad.3fr-raw-image 3fr   
com.hasselblad.fff-raw-image fff   
com.ilm.openexr-image        exr   Writable
com.kodak.raw-image          dcr   
com.konicaminolta.raw-image  mrw   
com.leafamerica.raw-image    mos   
com.leica.raw-image          raw   
com.leica.rwl-raw-image      rwl   
com.microsoft.bmp            bmp   Writable
com.microsoft.cur            --    
com.microsoft.dds            dds   Writable
com.microsoft.ico            ico   Writable
com.nikon.nrw-raw-image      nrw   
com.nikon.raw-image          nef   
com.olympus.or-raw-image     orf   
com.olympus.raw-image        orf   
com.olympus.sr-raw-image     orf   
com.panasonic.raw-image      raw   
com.panasonic.rw2-raw-image  rw2   
com.pentax.raw-image         pef   
com.phaseone.raw-image       iiq   
com.samsung.raw-image        srw   
com.sgi.sgi-image            sgi   
com.sony.arw-raw-image       arw   
com.sony.raw-image           srf   
com.sony.sr2-raw-image       sr2   
com.truevision.tga-image     tga   Writable
org.khronos.astc             astc  Writable
org.khronos.ktx              ktx   Writable
org.khronos.ktx2             --    Writable
org.webmproject.webp         webp  
public.avci                  avci  
public.avif                  avif  
public.avis                  --    
public.heic                  heic  Writable
public.heics                 heics Writable
public.heif                  heif  
public.jpeg                  jpeg  Writable
public.jpeg-2000             jp2   Writable
public.jpeg-xl               jxl   
public.mpo-image             mpo   
public.pbm                   pbm   Writable
public.png                   png   Writable
public.pvr                   pvr   Writable
public.radiance              pic   
public.svg-image             svg   
public.tiff                  tiff  Writable

An NSImage can have multiple ‘representations‘. These are essentially just different versions of the image. One representation might be the original vector form (e.g. an NSPDFImageRep). Another might be a rasterisation of that at a certain resolution. Yet another might be a rasterisation at a different resolution.

It gets more complicated, however, because some representations are merely proxies for other frameworks’ representations, like CGImage, CIImage or somesuch.

Nonetheless, for the simple case of a static bitmap image read from a file, generally NSImage produces just one representation, which is the full bitmap (as an NSBitmapImageRep). That’s the only case I’m going to discuss here, for simplicity’s sake (though likely the lessons apply to the other cases too).

Accessing / using an NSImage

Generally to use an NSImage you need a bitmap representation. e.g. to actually draw it to the screen.

Unless you manually create an NSImage from an in-memory bitmap, the bitmap representation is not loaded initially, but rather only when first needed.

Ultimately the load is triggered when something asks for the raw bytes of the bitmap (either you, directly in your code, or indirectly when you e.g. ask AppKit to draw the image).

Fetching the raw bytes of a bitmap from NSBitmapImageRep is not a trivial exercise. I’m going to gloss over the complexities (like planar data formats) and just talk about the common case of single-plane (“interleaved channels”) bitmaps.

For those, you can access the raw bytes via the bitmapData property.

Nominally, bitmapData just returns a uint8_t*.

In fact, bitmapData calls a lot of internal methods in a complicated fashion, with many possible code paths. What exactly it does depends on the underlying source of data, but in a nutshell it checks if the desired data has already been created / loaded (it’s cached in an instance variable) and if not it loads it, e.g. by calling CGImageSourceCreateImageAtIndex.

That’s what makes NSImage dangerous to use from multiple threads simultaneously.

Reading the cached bitmap data is essentially read-only (just some retain/autorelease traffic) so it’s safe to call from multiple threads concurrently (as long as something ensures the NSBitmapImageRep is kept alive the whole time and not mutated)

But loading or modifying it is not. As such, if you call bitmapData from multiple threads concurrently, and you don’t know for sure that it’s already fully loaded, you get a data race (also known as a “WTF does my app crash randomly?!” condition).

The consequences of that race vary. Maybe you “win” the race – one thread happens to run virtually to completion of bitmapData first, storing the fresh backing data into the caching instance member, and then all the other threads run and just return that same value – the ideal situation as everything works as intended.

Maybe you “lose” the race: every concurrent thread checks simultaneously and sees there’s no cached value, so they all – in parallel and redundant to each other – load the bitmap data and store it into the cache. They each return the one they created, even though ultimately only one thread wins – the last one to write into the cache – and the duplicate bitmap data that all the earlier threads created is deallocated. Even though pointers to them have been returned to you. And you might be in the middle of using them. Causing you to crash with a memory protection fault (or worse, read from some random other memory allocation that happened to be placed at the same address afterwards, reading essentially garbage).

Hypocritically, this is because Apple don’t follow their own rules on escaping pointers:

The pointer you pass to the function is only guaranteed to be valid for the duration of the function call. Do not persist the pointer and access it after the function has returned.

Apple’s Swift Standard Library > Manual Memory Management > Calling Functions With Pointer Parameters, subsection Pass a Constant Pointer as a Parameter.

The source code for the relevant NSBitmapImageRep methods is essentially:

- (uint8_t*)bitmapData {
    uint8_t **result = nil;
    [self getBitmapDataPlanes:&result];
    return *result;
}

- (void)getBitmapDataPlanes:(uint8_t***)output {
    [self _performBlockUsingBackingMutableData:^void (uint8_t* dataPlanes[5]) {
        *output = dataPlanes;
    }];
}

🤦‍♂️

Unfortunately, while _performBlockUsingBackingMutableData and its many similar siblings can be made safe, they are (a) all private and (b) not currently enforcing the necessary mutual exclusion. This could be corrected by Apple in future (although I wouldn’t hold your breath).

Why does it matter that NSImage is not thread-safe?

The crux of the problem is that you often have no good choice about it, because NSImage is a currency type used widely throughout Apple’s own frameworks, and you often have no control over what thread it’s created or used on.

For example, even using the very latest Apple APIs such as SwiftUI’s dropDestination(for:action:isTargeted:), you cannot control which thread the NSImages are created on (it appears to be the main thread, although that API provides no guarantees).

Similarly you have no control over where those images are used if you pass them to 3rd party code – including Apple’s. e.g. Image(nsImage:); possibly that only uses them on the main thread, but it might be pre-rendered the image a separate thread for better performance (to avoid blocking the main thread and causing the app to hang). In fact it should, in principle.

Loading an image – actually reading it from a file or URL and decompressing it into a raw bitmap suitable for drawing to the screen – should never be done on the main thread, because it can take a long time. A 1 GiB TIFF takes nearly 30 seconds on my iMac Pro, for example (and TIFF uses very lightweight compression, so it’s a relatively fast-to-read format). Anything involving the network could take an unbounded amount of time. Even small files – like a 20 MiB NEF – can take seconds to render because they are non-trivial to decode and/or decompress.

So you’re screwed on multiple levels: not only can you generally not guarantee what thread NSImage is born on nor used on, you can’t use it exclusively on the main thread because that will cause a terrible user experience.

What can you do?

In simple terms, the best you can realistically do is try ensure that all modifications to the NSImage (including implicit ones, such as loading a bitmap representation upon first use) happen exclusively in one thread [at a time]. For example, in my experiments, putting a lock around otherwise concurrent calls to bitmapData is enough to prevent any data races. Although I am mystified as to how I can still let the main thread draw the image concurrently without any apparent problems. 🤔

If you want to play it really safe, you have to create & pre-load each NSImage on a single thread (not the main thread), before ever sending it to another isolation domain. That means manually reimplementing things like drag and drop of images (because you can no longer work directly with NSImage with any drag & drop APIs, you have to instead use only – and all – the things that could potentially be images, like URLs or data blobs, and then translate those to & from NSImages manually).

Complicating all this is that NSImage is unclear about how its caching works. For starters, does this caching apply to the representations or is it a hidden, orthogonal system? Is it thread-safe? Etc.

You can supposedly modify the caching behaviour via the cacheMode property, but in my experience there is no apparent effect no matter what it is set it to (not on the image’s representations nor on render performance in the GUI).

It’s a shame that NSImage has been so neglected, and has so many glaring problems. Over the years Apple have seemingly tried to replace it, introducing new image types over and over again, but all that’s done is made everything more complicated.

var body: some View {
    SomeRootView {
        …
    }.task {
        let approximateGranularity = Duration.milliseconds(10)
        let threshold = Duration.milliseconds(50)

        let clock = SuspendingClock()
        var lastIteration = clock.now

        while !Task.isCancelled {
            try? await Task.sleep(for: approximateGranularity,
                                  tolerance: approximateGranularity / 2,
                                  clock: clock)

            let now = clock.now

            if now - lastIteration > threshold {
                print("Main thread hung for ",
                      (now - lastIteration).formatted(.units(width: .wide,
                                                             fractionalPart: .show(length: 2))),
                      ".",
                      separator: "")
            }

            lastIteration = now
        }
    }
}

You can adjust the two parameters – approximateGranularity and threshold – to suit your preferences. The overhead is quite tiny in CPU-usage terms, although be aware that this will cause the main thread to wake up frequently so it may have a noticeable, detrimental energy-usage impact. I suggest not deploying this to your users.

Perhaps it goes without saying, but a breakpoint set on the print statement enables you to debug deeper into hangs. Even without that, though, it can be illuminating just to have the log message – oftentimes you don’t notice that your app is hanging, because you don’t happen to be actively interacting with it in that moment. But your users might.