Provide a Preferences window in your Mac app built with Mac Catalyst so users can manage app preferences defined in a Settings bundle.
Mac apps typically display app-specific preferences using a Preferences window accessible through the standard Preferences menu item under the app menu in the menu bar.
Mac apps built with Mac Catalyst that include a
Settings file automatically get the Preferences menu item and a Preferences window. When a user selects the Preferences menu item, the system displays a Mac-friendly Preferences window based on the options provided in your Settings bundle. To learn about Settings bundles, see Implementing an iOS Settings Bundle.
Add a Preferences Window to Your App
To include a Preferences window in your Mac app, add a
Settings file to your Xcode project by pressing Command-N and selecting the Settings Bundle template from the Resources section under iOS. Then click Next to save the file to your project.
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. Your Mac app can prompt the user for a confirmation when they toggle the switch by including the following keys in the 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 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 the toggle switch element to show a subtitle:
Optional. A longer descriptive string to display under a toggle switch.