NSSavePanel: Adding an Accessory View

Share Button

Cocoa’s NSSavePanel allows one to programmatically add essentially arbitrary interface elements and functionality to it, in the form of an accessory view. In this post, I show a very simple accessory view example: allowing the user to control the file type (that is, suffix) of the file to be saved. I’ll present this in two contexts: first, in a purely Objective-C usage; and second, in the case of using an NSSavePanel inside a C/C++ function. In the latter case, I show an example of using a selector in a separate object, to handle “callbacks”. This post is aimed at novice Cocoa programmers; experienced programmers looking to add a file type selection are encouraged to check out JFImageSavePanel or  JAMultiTypeSavePanelController. Apple’s Customizing NSSavePanel shows other uses for the accessory view.

The NSSavePanel allows one to specify one or more file types; for example you could specify several image formats:

In some UI toolkits, there’s a built-in mechanism that allows the user to switch between types, generally using some pulldown or popup menu, in which the user chooses the file type by suffix or format name. The NSSavePanel does not provide this, so the programmer needs to add it. Here’s an unadorned NSSavePanel, where we’ve used those file types:

BasicSaveDialog

What we want is this:

FinalSaveDialog

I created an Xcode project, available on github, that demonstrates how to create a basic save panel, and several approaches for adding an accessory view.

The Basic Save Panel

The demo app’s xib file has several buttons that are used for launching save panels. Here’s the entirety of the code for a basic/unadorned version:

This gives us that basic save panel shown in the first image in this post.

Adding an Accessory View Programmatically

To add a control for the file type, we’ll use an NSPopUpButton, along with a label, and embed this in a view for layout purposes. This can done programmatically, or by loading UI elements from a Xib file. Here’s a bare-bones programmatic approach:

The API for adding an accessory view is just that: you only get to specify a single view; so, I created accessoryView as the “container” for the UI elements. To this, I add a label and an NSPopUpButton, populating the latter with the various choices we’ll present to the user. Note that this sort of ad-hoc “layout” is not really recommended — if you’re creating UI elements programmatically, the actual length of the label should be used, and constraints should be employed.

The File Type “Callback”

The selector used in  [popupButton setAction:@selector(selectFormat:)]  handles the user’s interactions with type selection popup. This setAction  function is called whenever the user changes the popup button.

Here, all we’re doing is simply changing the suffix of the file name that is shown at the top of the save panel, to match the current file format choice.

Update: if the user’s Finder Preference “Show all filename extensions” is off, or the panel’s extensionHidden property is YES, then the nameFieldStringValue may not get updated with the desired extension. A workaround (fix?) is to restrict the allowed file types to only the specified one, and then the URL for the selected file will get the correct extension.

Adding an Accessory View Defined in an XIB File

Generally, it might be preferable to craft the accessory view in Interface Builder. Here, I added a new NSViewController (cleverly named “AccessoryViewController”) and corresponding XIB file, and added a Label and PopUpButton, initializing the button’s menu items with the file type strings, corresponding to what I did programmatically:

SavePanelIB 1

The action selector in the view controller is exactly the same as I used in the programmatic approach. In order to do this, I added a property to the AccessoryViewController for the save panel:

The code, then, to launch the NSSavePanel with this XIB-defined accessory view is simple — we just create an AccessoryViewController by loading it from the nib file, and add it to the NSSavePanel:

 Launching an NSSavePanel From a C/C++ Function

In the preceding examples, the functions used to launch the save panel in these three versions were simply stuck in the app delegate, to keep the code in the demo as simple as possible. In general, the code would usually be in one or the other Cocoa objects (e.g. a subclassed NSViewController).

Occasionally, one might be coding in a context that would use a C/C++ function to launch a save panel. By implementing such a function in a “.mm” file, you can mix C, C++, and Objective-C, so code almost exactly  the same as the body of our  launchDefaultSavePanel will work:

Of course, this does not yet have the file type UI element. But we’re inside a C/C++ function, so what do we do about the  [popupButton setAction:@selector(selectFormat:)];  that we’d need to add?

In Cocoa, it’s possible to “tell” an object that it can use a selector from another, otherwise unrelated, object. So, we need to have an object that provides the necessary selector. Of course we already have one of those : the AccessoryViewController. So our C/C++ function looks like this:

What about doing this programmatically? We can of course create the label and NSPopupButton programmatically as we did in launchNibVersion . But, how do we provide the action selector? We can do this by creating an object that’s much like our AccessoryViewController, in that it provides that necessary selectFormat function and contains a pointer to the save panel:

The final piece of the puzzle: how do we use this object, so its implementation of selectFormat can be used to handle the programmatically created NSPopUpButton? Note that the NSButton class uses NSButtonCell to implement its user interface; that latter class is subclassed from NSCell, which offers a -setTarget  function, which sets the target object to receive action messages. So we create a  PopUpButtonHandler , and tell the popup button to use it:

I hope this exercise shows how easy it is to add functionality to the NSSavePanel (as well as to the NSOpenPanel) by adding an accessory view. The excursion into using Cocoa inside a strictly C/C++ function allowed me to demonstrate the use of the -setTarget   function in the NSCell class; this functionality is significant because the NSCell is a very fundamental class in Cocoa (particularly its NSActionCell subclass).