File Handling

Your app can use standard system-provided dialogs to let the user interact with the file system in order to open and save files.

Open Dialogs

An Open dialog provides a consistent way to locate an item in the file system for opening, importing, insertion, or selection. An Open dialog can be displayed as a standalone window (an app can display only one Open dialog at a time) or as a sheet attached a specific window.

Decide whether to display an Open dialog as a standalone window or sheet. If the dialog pertains to your entire app, such as when opening a document for editing, present it as a standalone window. If the dialog pertains to a specific window, such as when inserting an image into a document, it should be attached to the corresponding window as a sheet.

Default to a reasonable location. In some apps, it makes sense to default to a standard location in the user’s Home folder, like the Documents folder or desktop. In other apps, it makes sense to default to the last location the user selected. When iCloud synchronization is enabled, the app’s iCloud folder is generally the best default location.

Consider adding a descriptive title or message. Not all Open dialogs need titles or messages, but if the dialog’s purpose is unclear you can use these attributes to provide context. A title should indicate what the user should choose—for example, Choose Photo. You can include a more detailed message if the title alone isn’t sufficient. Note that titles aren't visible on sheets.

Customize the title of the Open button to reflect the task. If the dialog lets the user select a file for insertion, for example, change the title of the Open button to Insert.

Let people open documents in expected ways. In a document-based app, people expect to open documents for editing by selecting File > Open or by pressing the corresponding keyboard shortcut, Command-O. See File Menu.

Consider providing a way to reopen recent documents. In document-based apps, documents are often edited through several working sessions. For example, a user might close a document at the end of the day and open it the next morning to continue working on it. Many apps include an Open Recent item in the File menu that lets people reopen recently opened documents in a single step, without using an Open dialog to locate them.

Allow multiple file selection if it makes sense. If your app includes an image insertion feature, for example, it may be useful and efficient to let the user insert multiple images at once.

Extend the functionality of the Open dialog if appropriate. If it makes sense in your app, you can add a custom accessory view containing useful settings or options to the Open dialog. For example, the Open dialog in TextEdit includes an Options section that lets people specify different encodings.

Consider including a pop-up button that enables filtering for specific types of files. Default to a reasonable filter and disable files that don’t match the specified criteria so they can’t be chosen. Be sure to include an All Applicable Files option in the pop-up button so the user can browse all supported file types if they prefer.

For developer guidance, see NSOpenPanel.

Save Dialogs

A Save dialog provides a consistent way to specify a file name and output location when saving or exporting a file. A Save dialog is typically attached as a sheet to the window being saved and has two states, collapsed and expanded, which can be toggled by clicking a disclosure button. In its collapsed state, the dialog contains a file name field, a pop-up button for selecting an output location, a field for tagging the saved file, an optional file format pop-up button, an optional accessory view for displaying custom save options, a Save button, and a Cancel button. In expanded state, the dialog includes the same elements but provides a much broader view for browsing the file system to locate an output folder.

Tip An app can display close confirmation dialog when the user tries to close an unsaved document and Auto Save isn’t enabled. A close confirmation dialog is a Save dialog containing descriptive text that asks the user if they’d like to keep the document. The user can choose to save, cancel, or delete the document.

Enable Auto Save if your app is document-based. In general, people expect their content to be saved continuously and without intervention. Opt in to Auto Save so they can rely on these behaviors in your app. See Auto Save.

Default to a reasonable output folder. In some apps, it make sense to default to a standard output folder in the user’s Home folder, like the Documents folder or desktop. In other apps, it makes sense to default to the last output folder the user selected. When iCloud synchronization is enabled, the app’s iCloud folder is often a good default output folder.

Let people choose whether to view the extension of the file being saved. The file extension should be hidden by default, but users should be able to view it if desired by deselecting a “Hide extension” checkbox. Any user change to the state of this checkbox should be reflected in the future Save dialogs your app displays—even after the user quits and reopens your app.

Prefill the file name field. The first time a document is saved, the file name field should contain the text “Untitled.” When saving a copy of a document or exporting a document, the file name field should contain the document’s name. Any text in the file name field should be selected so the user can immediately begin typing to change it.

Let the user choose an output format if your app can save in multiple file formats. Output formats, when present, are displayed via a pop-up button beneath the output location.

Extend the functionality of the Save dialog, if appropriate. If it makes sense in your app, you can add a custom accessory view containing useful settings or options to the Save dialog. For example, the Save dialog when saving Mail messages as files contains an option for including attachments.

For developer guidance, see NSSavePanel.