MacAppSettingsUI

A package for make easier implementing a structure of settings / preferences UI for macOS AppKit-based apps.

Design and Features

Preferences-Style Toolbar with Animation

The window has preferences-style toolbar and native switching animation. It also supports “Reduce Motion” feature of accessibility.

Window Title

Set active pane name as a window title automatically when panes are switched.

Window Title with Active Pane Name on Window Menu

Display window title with pane name on the Window menu automatically.

Only Close Button

Basically, the window only has a close button, but a zoom button is optional for per-pane.

Press Escape Key to Close

We can use the Escape key ⎋ or ⌘. action to close the window.

Restorable Window Frame

The settings Window supports autosave frame via UserDefaults. The last window position can be restored automatically.

Supported for Renamed “Settings”

On before macOS Ventura, “Settings” was “Preferences”. This module can also support renamed “Settings” after Ventura.

More details of this design (Japanese): macOS Venturaからの新しい“Settings”表記と、旧“Preferences”表記からの移行

Layout Guide (experimental)

I have prepared a simple layout guide and a wireframing feature to help you build the standard setting layout. Please check the “Developer” tab on the demo app, DeveloperSettingsPaneViewController and SettingsPaneContainerView.

Core Files

SettingsWindow

Window for Settings window.

SettingsWindowController

WindowController for Settings window.

SettingsTabViewController

WindowController’s contentViewController. It manages tab transitions with a lazy loading architecture — pane content is loaded on demand when a tab is first selected, rather than all at once. A loadingView is displayed during transitions. You can show a loading label by setting showsLoadingLabel to true and customize its text with loadingLabelText.

If you prefer eager loading of all tabs, call loadAllTabs() explicitly.

SettingsPaneViewController

The base view controller for setting pane. You can use this class to customize your own.

Override loadPaneContent(completion:) to perform asynchronous content loading before the pane is displayed. The isPaneContentLoaded flag is managed automatically by SettingsTabViewController.

Each pane captures its preferredPaneSize automatically in viewDidLoad(). If your subclass adds subviews or modifies constraints after super.viewDidLoad(), call resolvePreferredPaneSize() at the end of your viewDidLoad() to recapture the correct size.

SettingsPaneContainerView

This is a convenient container view for layouts. It is disabled by default; if you wish to use it, first enable it using the setContentContainerView(maximumWidth: labelLayoutGuideWidth:) method of the SettingsPaneLayoutGuide. Then add any contents to this container view.

Please check the “Developer” tab on the demo app, DeveloperSettingsPaneViewController in DemoViewControllers.swift and SettingsPaneContainerView.

SettingsPaneLayoutGuide

A protocol for a layout guide using SettingsPaneContainerView.

Install

Use SwiftPM.

Usage

To set panes of settings window, there are two ways of them.

A. Initialize SettingsWindowController with the panes as an array

// First, initialize the SettingsWindowController instance
let settingsWindowController = SettingsWindowController(with: [/*panes*/])

// …like this:
let settingsWindowController = SettingsWindowController(with: [
	SettingsPaneViewController(tabName: "General",
							   tabImage: NSImage(systemSymbolName: "gearshape", accessibilityDescription: nil),
							   tabIdentifier: "general",
							   isResizableView: false),
	SettingsPaneViewController(tabName: "View",
							   tabImage: NSImage(systemSymbolName: "eyeglasses", accessibilityDescription: nil),
							   tabIdentifier: "view",
							   isResizableView: true),
	SettingsPaneViewController(tabName: "Extensions",
							   tabImage: NSImage(systemSymbolName: "puzzlepiece.extension", accessibilityDescription: nil),
							   tabIdentifier: "extensions",
							   isResizableView: false),
	SettingsPaneViewController(tabName: "Advanced",
							   tabImage: NSImage(systemSymbolName: "gearshape.2", accessibilityDescription: nil),
							   tabIdentifier: "advanced",
							   isResizableView: false),
])

// That’s all. Then you can show the settings window.
settingsWindowController.showWindow(nil)

B. Set panes to a SettingsTabViewController instance

func set(panes: [SettingsPaneViewController])
func add(panes: [SettingsPaneViewController])
func insert(panes: [SettingsPaneViewController], at index: Int)
func insert(tabViewItem: NSTabViewItem, at index: Int)

To remove any pane, use NSTabViewController’s methods.

Appearance of Tabs

There are properties of tab item in SettingsPaneViewController.

tabName

Default tab name, alias of NSViewController.title.

tabImage

Icon for a tab.

tabIdentifier

Should set to a unique name.

localizeKeyForTabName

This key is used for localizing tab name process automatically.

If you use this, SettingsTabViewController replaces tabName with the localized tab name. You can disable this feature with using a property disablesLocalizationWithTabNameLocalizeKey on SettingsTabViewController.

This is useful when initializing view controllers in Interface Builder, but in normal cases, use String(localized: “ANY KEY”) (or NSLocalizedString()) for tabName property.

Controlling window resizing behavior on a per-pane

SettingsPaneViewController has the property isResizableView; setting true to allow window resizing only while the pane is active. The default value is false. Check the Demo implementation and Main Storyboard file.

Toolbar minimum width clamping

SettingsTabViewController has a clampsToToolbarMinimumWidth property (default: true). When enabled, all pane widths are clamped to at least the minimum content width imposed by the toolbar layout. This prevents visual flicker when a pane's preferred width is narrower than the toolbar requires.

License

See LICENSE for details.