Add a preferences window to your macOS app in minutes
Switch branches/tags
Nothing to show
Clone or download
Latest commit 83e5bbe Oct 18, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Example Upgrade to Swift 4.2 and confirmed working with Mojave Oct 4, 2018
Preferences.xcodeproj 0.2.0 Oct 10, 2018
Sources/Preferences Fix Auto Layout satisfiability (#5) Oct 10, 2018
.editorconfig Init Jun 29, 2018
.gitattributes Init Jun 29, 2018
.gitignore Init Jun 29, 2018
Package.swift Upgrade to Swift 4.2 and confirmed working with Mojave Oct 4, 2018
Preferences.podspec 0.2.0 Oct 10, 2018
license Init Jun 29, 2018
readme.md SPM → SwiftPM Oct 18, 2018
screenshot.gif Init Jun 29, 2018

readme.md

Preferences

Add a preferences window to your macOS app in minutes

Just pass in some view controllers and this package will take care of the rest.

Requirements

  • macOS 10.12+
  • Xcode 10+
  • Swift 4.2+

Install

SwiftPM

.package(url: "https://github.com/sindresorhus/Preferences", from: "0.2.0")

Carthage

github "sindresorhus/Preferences"

CocoaPods

pod 'Preferences'

Usage

Run the PreferencesExample target in Xcode to try a live example.

First, create a couple of view controllers for the preference panes you want. The only difference from implementing a normal view controller is that you have to add the Preferenceable protocol and implement the toolbarItemTitle and toolbarItemIcon getters, as shown below.

GeneralPreferenceViewController.swift

import Cocoa
import Preferences

final class GeneralPreferenceViewController: NSViewController, Preferenceable {
	let toolbarItemTitle = "General"
	let toolbarItemIcon = NSImage(named: NSImage.preferencesGeneralName)!

	override var nibName: NSNib.Name? {
		return "GeneralPreferenceViewController"
	}

	override func viewDidLoad() {
		super.viewDidLoad()

		// Setup stuff here
	}
}

AdvancedPreferenceViewController.swift

import Cocoa
import Preferences

final class AdvancedPreferenceViewController: NSViewController, Preferenceable {
	let toolbarItemTitle = "Advanced"
	let toolbarItemIcon = NSImage(named: NSImage.advancedName)!

	override var nibName: NSNib.Name? {
		return "AdvancedPreferenceViewController"
	}

	override func viewDidLoad() {
		super.viewDidLoad()

		// Setup stuff here
	}
}

In the AppDelegate, initialize a new PreferencesWindowController and pass it the view controllers. Then add an action outlet for the Preferences… menu item to show the preferences window.

AppDelegate.swift

import Cocoa
import Preferences

@NSApplicationMain
final class AppDelegate: NSObject, NSApplicationDelegate {
	@IBOutlet private var window: NSWindow!

	let preferencesWindowController = PreferencesWindowController(
		viewControllers: [
			GeneralPreferenceViewController(),
			AdvancedPreferenceViewController()
		]
	)

	func applicationDidFinishLaunching(_ notification: Notification) {}

	@IBAction
	func preferencesMenuItemActionHandler(_ sender: NSMenuItem) {
		preferencesWindowController.showWindow()
	}
}

API

protocol Preferenceable: AnyObject {
	var toolbarItemTitle: String { get }
	var toolbarItemIcon: NSImage { get }
}

class PreferencesWindowController: NSWindowController {
	init(viewControllers: [Preferenceable])
	func showWindow()
	func hideWindow()
}

FAQ

How is it better than MASPreferences?

  • Written in Swift. (No bridging header!)
  • Swifty API using a protocol.
  • Fully documented.
  • The window title is automatically localized by using the system string.
  • Less code (and less chance of bugs) as it uses NSTabView instead of manually implementing the toolbar and view switching.

Related

You might also like my apps.

License

MIT © Sindre Sorhus