Let users manage app settings defined in a Settings bundle through a system-provided preferences window.
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 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:
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:
Optional. A dictionary that defines the prompt to present to users when they attempt to turn on the switch.
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:
Required. Must be set to
Required. A string with the title of the prompt. The title might not appear on some devices.
Required. A string with the body text that the prompt displays.
Optional. A string with the text displayed in the prompt's confirmation button. The toggle switch value changes when the user clicks this button.
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:
Optional. A longer descriptive string to display under a toggle switch.