Sample Code

Creating and Customizing the Touch Bar

Use and customize your app’s Touch Bar for macOS.

Download

Overview

You can use the Touch Bar to display interactive content and controls of supported models of MacBook Pro.

The sample uses a split-view controller architecture to navigate various ways to use the NSTouchBar class. The primary view controller, the MasterViewController class, shows the available use cases. When you select one of the use cases, the secondary view shows what you can do with the Touch Bar controls.

The description in each secondary view controller reflects its target item. For example, the ButtonViewController class shows how to use an NSButton object. All view controllers are hosted in a separate storyboards.

Refer to this sample if you are looking for specific ways to create NSTouchBar instances in a variety of situations:

  • Button - An NSCustomTouchBarItem with an NSButton.

  • Segmented Control - An NSCustomTouchBarItem that uses an NSSegmentedControl.

  • Group - An NSGroupTouchBarItem that groups together touch Bar items.

  • Fancy Group - A more advanced NSGroupTouchBarItem.

  • Custom View - An NSCustomTouchBarItem that uses an NSView.

  • Scroll View - An NSCustomTouchBarItem that uses an NSScrollView.

  • Color Picker - An NSColorPickerTouchBarItem.

  • Slider - An NSSliderTouchBarItem that uses an NSSlider.

  • Popover - An NSPopoverTouchBarItem that presents another set of Touch Bar items.

  • Popover with Scrubber - An NSPopoverTouchBarItem with an NSScrubber view.

  • Scrubber - An NSCustomTouchBarItem that uses an NSScrubber view.

  • Text Field Candidate List - An NSCustomTouchBarItem with a Candidate List.

  • Text View - An override for the NSTextView class in the NSTouchBar.

  • Sharing Service - An NSSharingServicePickerTouchBarItem.

  • Visibility Priority - The visibility priority of NSTouchBarItem.

  • TouchBar Images - Images used on buttons in the NSTouchBar.

The sample also displays a secondary window that shows a typical use case with the Touch Bar which uses an NSScrubber to pick an image that changes the window background.

Simulate the Touch Bar in Xcode

If you’re adopting Touch Bar support for your app, but running Xcode on a Mac without a Touch Bar, you can enable the Xcode Touch Bar simulator by choosing Window > Show Touch Bar in Xcode.

Create the Touch Bar

You create a Touch Bar by adding one to a view controller in the storyboard, or by creating one programmatically by overriding NSResponder's makeTouchBar() function. The following example demonstrates overriding makeTouchBar() for an NSViewController that displays a color-picker button or NSColorPickerTouchBarItem.

override func makeTouchBar() -> NSTouchBar? {
    let touchBar = NSTouchBar()
    touchBar.delegate = self
    
    touchBar.customizationIdentifier = colorPickerBar
    touchBar.defaultItemIdentifiers = [selectedItemIdentifier]
    touchBar.customizationAllowedItemIdentifiers = [selectedItemIdentifier]
    touchBar.principalItemIdentifier = selectedItemIdentifier
    
    return touchBar
}

Add Content to the Touch Bar

You add content to the Touch Bar by adopting NSTouchBarDelegate protocol and implementing touchBar(_:makeItemForIdentifier:). The following example adds a Sharing Service button:

func touchBar(_ touchBar: NSTouchBar, makeItemForIdentifier identifier: NSTouchBarItem.Identifier) -> NSTouchBarItem? {
    guard identifier == services else { return nil }
    
    let services = NSSharingServicePickerTouchBarItem(identifier: identifier)
    services.delegate = self
    
    return services
}

Add a Scrubber to the Touch Bar

The NSScrubber class provides a way for you to add a flexible, horizontally-oriented picker. You add a scrubber view to an NSCustomTouchBarItem, and that view adds a scrubber to the Touch Bar:

func touchBar(_ touchBar: NSTouchBar, makeItemForIdentifier identifier: NSTouchBarItem.Identifier) -> NSTouchBarItem? {
    let scrubberItem: NSCustomTouchBarItem
    
    scrubberItem = NSCustomTouchBarItem(identifier: identifier)
    scrubberItem.customizationLabel = NSLocalizedString("Choose Photo", comment: "")
    
    let scrubber = NSScrubber()
    scrubber.register(NSScrubberImageItemView.self, forItemIdentifier: itemViewIdentifier)
    scrubber.mode = .free
    scrubber.selectionBackgroundStyle = .roundedBackground
    scrubber.delegate = self
    scrubber.dataSource = self
    scrubber.showsAdditionalContentIndicators = true
    scrubber.scrubberLayout = NSScrubberFlowLayout()
    
    scrubberItem.view = scrubber
    
    // Set the scrubber's width to be 400.
    let viewBindings: [String: NSView] = ["scrubber": scrubber]
    let hconstraints =
        NSLayoutConstraint.constraints(withVisualFormat: "H:[scrubber(400)]",
                                       options: [],
                                       metrics: nil,
                                       views: viewBindings)
    NSLayoutConstraint.activate(hconstraints)
    
    return scrubberItem
}

Add a Popover to the Touch Bar

An NSCustomTouchBarItem class shows its own Touch Bar when the user taps and holds on it. This class is a two-state control that can expand into its second state, that shows the contents of a bar it owns. The second Touch Bar is displayed when this item is “popped.” The following example shows how to create a NSPopoverTouchBarItem with an NSScrubber view with set of numbered text items:

func touchBar(_ touchBar: NSTouchBar, makeItemForIdentifier identifier: NSTouchBarItem.Identifier) -> NSTouchBarItem? {
    guard identifier == scrubberPopover else { return nil }
    
    let popoverItem = NSPopoverTouchBarItem(identifier: identifier)
    popoverItem.collapsedRepresentationLabel =
        NSLocalizedString("Scrubber Popover", comment: "")
    popoverItem.customizationLabel =
        NSLocalizedString("Scrubber Popover", comment: "")
    
    let scrubber = PopoverScrubber()
    scrubber.register(NSScrubberTextItemView.self, forItemIdentifier: textScrubber)
    
    scrubber.mode = .free
    scrubber.selectionBackgroundStyle = .roundedBackground
    scrubber.delegate = self
    scrubber.dataSource = self
    scrubber.presentingItem = popoverItem
    
    popoverItem.collapsedRepresentation = scrubber
    
    popoverItem.popoverTouchBar =
        PopoverTouchBarSample(presentingItem: popoverItem)
    
    return popoverItem
}

See Also

First Steps

Integrating a Toolbar and Touch Bar into Your App

Build a toolbar in your app’s window, with a corresponding Touch Bar, for quick access to app features.

class NSTouchBar

An object that provides dynamic contextual controls in the Touch Bar of supported models of MacBook Pro.

protocol NSTouchBarDelegate

A protocol that allows you to provide the items for a bar dynamically.

protocol NSTouchBarProvider

A protocol that an object adopts to create a bar object in your app.