Article

Displaying a Preferences Window

Let users manage app settings defined in a Settings bundle through a system-provided preferences window.

Overview

Mac apps typically display app-specific preferences using a preferences window. This window is accessible through the standard Preferences menu item found under the app menu in the menu bar. iPad apps containing a Settings.bundle file automatically get a preferences window when the app runs in macOS. To learn about Settings bundles, see Implementing an iOS Settings Bundle.

When a user runs your app on their Mac device and selects the Preferences menu item, the system displays a Mac-friendly preferences window based on the options provided in your Settings bundle. You can further enhance the user experience by adding child panes and optional Mac-specific keys to your Settings bundle.

Add Toolbar Tabs to the Preferences Window

A Settings bundle can include one or more child panes that allow you to organize your preferences hierarchically (see Hierarchical Preferences). In iOS, the Settings app displays a child pane as a preference row. When the user taps the row, the app displays a new view showing the preferences defined in the child pane's property list file.

In macOS, the preferences window displays a child pane as a tab on the window’s toolbar. When the user clicks the tab, they see the preferences provided in the child pane's property list file.

The tab for a child pane displays the pane’s title and a system-provided icon. To customize the icon, add the following key to the child pane's property list file:

Icon

Optional. A string with the name of the image file to display as the toolbar tab icon in the preferences window.

You must include the image file in the Settings bundle that contains the child pane's property list file.

Confirm Changes Made with a Toggle Switch

Another element of the Settings bundle is the Toggle Switch Element, which displays an ON/OFF switch that the user can toggle. For iPad apps running in macOS, you can prompt the user for a confirmation when they toggle the switch, by including the following keys in your toggle switch element:

TrueConfirmationPrompt

Optional. A dictionary that defines the prompt to present to users when they attempt to turn on the switch.

FalseConfirmationPrompt

Optional. A dictionary that defines the prompt to present to users when they attempt to turn off the switch.

Each dictionary contains the following keys that define the contents of the prompt:

Type

Required. Must be set to PSConfirmationPrompt.

Title

Required. A string with the title of the prompt. The title might not appear on some devices.

Prompt

Required. A string with the body text that the prompt displays.

ConfirmText

Optional. A string with the text displayed in the prompt's confirmation button. The toggle switch value changes when the user clicks this button.

DenyText

Optional. A string with the text displayed in the prompt's cancel button. The toggle switch value doesn't change when the user clicks this button.

Display Subtitles for Toggle Switches

Some iOS apps show descriptive text in a subtitle below a toggle switch, by using a group item with footer text. While the Preferences window supports this approach, the appearance on a Mac isn't ideal. Instead, include the following key in your toggle switch element to show a subtitle:

Description

Optional. A longer descriptive string to display under a toggle switch.

See Also

User Interface

Toolbar

Provide a space for controls under a window's title bar and above your custom content.

Touch Bar

Display interactive content and controls in the Touch Bar.