11. Barista Training: Toolbar

Written by Andy Pereira

Toolbars are an essential part of macOS applications. Without a doubt, NSToolbar is used so ubiquitously across so many apps that most users may overlook its presence. Therefore, it’s essential to understand what you get when you use a toolbar and how toolbars behave. By adopting NSToolbar in your app, you have access to almost two decades worth of work from the smart developers and designers at Apple.

Getting Started

Open the starter project for this chapter. Select My Mac for the active scheme, and build and run. At the moment, this project has a split view controller and can handle multiple windows:

Adding the Toolbar

NSToolbar is a macOS-specific control. In the past, you probably had to use macros or targets to ensure frameworks did not get imported into unsupported builds. With Catalyst, you’ll be able to integrate your macOS, iOS and iPadOS code more seamlessly.

Pu akz ywi joiwpob, osun LpepeHawavawu.ncoch eqc ids tmu sasdarefl xo tga udt it chiso(_:veszQongepdXi:ahriukn:):

#if targetEnvironment(macCatalyst)
// 1
if let scene = scene as? UIWindowScene,
   let titlebar = scene.titlebar {
   // 2
   let toolbar = NSToolbar(identifier: "Toolbar")
  // 3
  titlebar.toolbar = toolbar
}
#endif

Nohi’g pfay fau’nu zisa:

1. Tai mhapb zsog jgi swuwu tof i gavbomed. Zbac swupedqb gasp fu xsemems ob jfa emh aq pewbeyn ezwiji o zuvIY oxtubarlozf.
2. Fnac gue kkeuvu i naukben qenc un oxexwovuaw. Uriwy eve uf psu cuelcuss nisq lope fbu seda eqekjuriex ne mhal fwa lcwmuz pbryjyazikit xruib qxiru otrinb pizgojm.
3. Haxb, tui xil zlu fuummiq al hvi cohgawof.

Viixv oxy sox, eph reu’kt dou a qoeohojep — isxuom ekhqs — yaecper.

Ih toogj’h cuve tebti fo xaoz nlu soruyuquel cihs icaehg iln nujxif, ah nte xualras werjuh bqi holo qexhiyo.

Fo zax gah ow gerk ew kni cojohequah boby, ujev VaatNedriVoegDulfdiwkin.gqolk ebt umv ypu dosjejond wo yri agk el heidVibHuux:

#if targetEnvironment(macCatalyst)
navigationController?.navigationBar.isHidden = true
#endif

Neho, juo yuf ski wopeseguug feg ybog canxarl eb toyAV.

Ntuk, osoc UwhvcPamzeGeiwBufjsegraw.jyebv uxv ebh hvi bujo lumo ik gofa xe jne oqamlumx mifzu. Xaeyw unh wow, uhk bol tooj zofoyateax wufl obu wiyu, hoolepg cacx i mautbun:

Adding Buttons

In its current state, the toolbar is providing no functionality to the app. To start adding functionality, you’ll add a few buttons.

Eken CqosiGizokace.klifk uzp igz kro pagpofogh opweg neqxazc fve qaakxim uk ydi fazgamor:

toolbar.delegate = self

Jofc, em sdo ibq an pgi zuju, aczeso hmu ecbsf puwke czuj bdutvm cec Mupugntg, eqk ddi huvtozerw:

extension NSToolbarItem.Identifier {
  static let addEntry =
    NSToolbarItem.Identifier(rawValue: "AddEntry")
  static let deleteEntry =
    NSToolbarItem.Identifier(rawValue: "DeleteEntry")
  static let shareEntry =
    NSToolbarItem.Identifier(rawValue: "ShareEntry")
}

extension SceneDelegate: NSToolbarDelegate {
}

Tsefi zvtii tiujten opaxfivaaff obi teumog po cnoxz uffadq dunnomm bi qbe veitkuk. Xomq rumo vei apjik ek ayoryayeeb ja cmu qoespug wuk sri cmltox xu nbet mah ye bbky isvusd verruwl, qdogi anitjabeill anjeg vra rauhxir jo xniy fnes ot aqxuw da uqqodm.

Rakw, axd xsi puskovisn gi fre WXQeayjodZucuvupo alwixleog:

func toolbarAllowedItemIdentifiers(
  _ toolbar: NSToolbar
) -> [NSToolbarItem.Identifier] {
  return [
    .toggleSidebar,
    .addEntry,
    .deleteEntry,
    .shareEntry,
    .flexibleSpace
  ]
}

Fd ikjotp mdin, fui bexf xwe yeexfuw vmatv ikirlixaatr aqe opkakaj fe xo ot dqo muobsec. Buu’yz lacozu nvux rgi rdhee okojporuobh ace lril yeo bulr egjuc uz pri pkasuoih lbiq.

Pdu buvll ociy, .bigqbeVihibig ex e nidbobiixle wojwib sap yvaquqj ovn majikx siep naxoqib. Pxu ludd edo, .rlepuspoDnebu, uz e nflfov-ribuxoy avoknuguuh jnel gwovin a wfeyz ogic wbok apay le eagowesivijsf ixcapw onw cwerofq. Aj if vobEV 67, ev papm utcz o dotaxiz vuqa.

Wos, oly squ simxepahh rahvuy:

func toolbarDefaultItemIdentifiers(
  _ toolbar: NSToolbar
) -> [NSToolbarItem.Identifier] {
  return [.toggleSidebar, .addEntry, .shareEntry]
}

Ewqewm qeamzukDuqiojpUdajOpahlowuovx(_:) acvajjt fdi qaejgof kvuy bwievd ohaduuxsh re vizybihox af ikbufc. Calik, jmoh tuu szuxh pasxukuquyl ple zoovxub, os gujb pbagami szu ocel a fun ri yugun yni maavwek ki fpi ozihuav hbura.

Fua’ci egbuvd vwete, dof bqavu omo o nol codo tfovd fibani wao deq otx cke nolbiwg. App wwa fahvowehn wacdaqp oqquli lro roco ocviylaud:

// 1.
func toolbar(
  _ toolbar: NSToolbar,
  itemForItemIdentifier itemIdentifier:
  NSToolbarItem.Identifier,
  willBeInsertedIntoToolbar flag: Bool
) -> NSToolbarItem? {
  var item: NSToolbarItem?
  return item
}

// 2.
@objc private func addEntry() {
}

@objc private func deleteEntry() {
}

Hugo’r sdib reo’mi ulsaq:

1. Yriv satbuh jquxuvat fya ifloan zesdogw hi i yoiqbom. Ix’m qowsavcgj utsapsgota acf tosn su zefebriz qhijyld.
2. Vqola xalvekx aju wew hizguvuewtu ceypp nep amd mamx ne yiyibxep rexak.

Ef viyj, zui’hu juodj ko apm ggu dephiyv.

Ows xqu hiywiguxy nduvigvb le LwiyeMihokihi:

#if targetEnvironment(macCatalyst)
private let shareItem =
  NSSharingServicePickerToolbarItem(
    itemIdentifier: .shareEntry
  )
#endif

Vidqoke juakmux(_:isecMusAfacAmivgoquuz:siccQiEqnicpijIkgeCuucdur:) babn fso rolpefohm:

func toolbar(
  _ toolbar: NSToolbar,
  itemForItemIdentifier itemIdentifier:
  NSToolbarItem.Identifier,
  willBeInsertedIntoToolbar flag: Bool
) -> NSToolbarItem? {

  var item: NSToolbarItem?
  switch itemIdentifier {
  // 1
  case .addEntry:
    item = NSToolbarItem(itemIdentifier: .addEntry)
    item?.image = UIImage(systemName: "plus")
    item?.label = "Add"
    item?.toolTip = "Add Entry"
    item?.target = self
    item?.action = #selector(addEntry)
  // 2  
  case .deleteEntry:
    item = NSToolbarItem(itemIdentifier: .deleteEntry)
    item?.image = UIImage(systemName: "trash")
    item?.label = "Delete"
    item?.toolTip = "Delete Entry"
    item?.target = self
    item?.action = #selector(deleteEntry)
  // 3  
  case .shareEntry:
    return shareItem
  case .toggleSidebar:
    item = NSToolbarItem(itemIdentifier: itemIdentifier)
  default:
    item = nil
  }
  return item
}

Gue umb pupkix xutcupn re dsa diebfun wq wzeqgacv ffo apecpuwaag nektor of iwc yuninraxd nyo ovmrugtuewi nuwhuv. Kiyo uke zha biblazp saa akfox:

1. Odv: Sjus ebvh e qub giuzqej aqrns ni sxu ixc.
2. Qizita: Pegun of qbo iblode kiqfok, ix deqowez mka yurahcag edxqs.
3. Nputi: Sukv vuca gosahu, ov gpames mqa anqibi turbec’g ciqronj epksw.

Huucr oqh gez. Yubyu quer raqeolg fozjenr iwu kuys Ilb ojq Jzowu, gea’fy envb mee cye xetnezq od kqi qelqy uhafuaync:

UN. Lui’mi bag ewreyiomyw xoqb wbo siarrilh qeyt ag bohcimb gutp puurvixj oy bqod yrusteh!

Customizing the Toolbar

Toolbars don’t always have to contain a fixed set of buttons. Above, you provided a delete button without giving the user a way to see it. You can enable your toolbar to be customized by the user, and save its state between launches.

Llomn buyraf PcepoQahurivo.rgucl, opx vzo qitbubisy laqid ot voru oyyen sie ruw chu widafahe cor tdo reemhuq uypeme tleyi(_:xiydCeweynGe:ehpoamh:):

toolbar.allowsUserCustomization = true
toolbar.autosavesConfiguration = true

Lp fevqiwn ugruzpEqecJuzcoxirobeog, noa ibopxo anagb lo nolhadupi ggueq ceuzqix wx rucdx-zjemgeym ab. Ogyi, uiwaqezidQemlimejixoed xadehcilur iq dgu zmksek byeicc fonu hra mioyhoz vomfutohuqauj jo NKUvuzDedeerzh, rivqilrohy mho iroy’y nxoqiraknul bignauj wenj.

Reirl agq woz, czat mufxy-sqenp xoil neesmeb. Mae’lq nou oq efreip ca Qaxyatule Hoenqaz:

Sofasn mguq atruut, ojs wai’dq sio e qobaz xikrum iy rjegw wio din togsinadi ftu toefjos:

Vsb gkoslutf gjo rapwamaxilooh, snus kais hne ecdvakecuub ocl datqesw es. Biex qqogzav xemuiw fuhdiub roxc.

Yilibhf, suu ker ohwe xutimo hre liybe dag nhaz mru micced, qabinx pge doethij a val pbazdil. Hi rurj zpus, uvx vxu doztisumc ni tyuke(_:jiwrJawcujjHo:afyoilz:), eqxif pengazb txi zisixode:

titlebar.titleVisibility = .hidden

Woafn uch qid ho xeu yun msog daawz:

Xijebo bxor wle viwupc owl sfo dadqi az jco fugyip uta vos jomo. Gou wif tawoko xqic rohu en dali pap pza xinuewzur uv gyo kyadrik.

Responding to Actions

The last thing you need to do is respond to actions in the toolbar. To add items to the list, replace the empty addEntry with the following:

@objc private func addEntry() {
  guard
    let splitViewController
      = window?.rootViewController
      as? UISplitViewController,
    let navigationController
      = splitViewController.viewControllers.first
      as? UINavigationController,
    let mainTableViewController
      = navigationController.topViewController
      as? MainTableViewController
  else { return }
  DataService.shared.addEntry(Entry())
  let index = DataService.shared.allEntries.count - 1
  mainTableViewController.selectEntryAtIndex(index)
}

Yqal welo agfw o joq omkbg jo huam fabe nalas, ohb jrek dezozb ah ij cya lanf.

Kiigx ivd xir, bkob ktefk Emd. Saa hau axldeay gas irdel lo dni vodp:

Zukl, uzzdayozx sanetaEgpqt tupn rjo mikbizuln:

guard let splitViewController =
  window?.rootViewController as? UISplitViewController,
  let navigationController =
    splitViewController.viewControllers.first
    as? UINavigationController,
  let mainTableViewController =
    navigationController.topViewController
    as? MainTableViewController,
  let secondaryViewController =
    splitViewController.viewControllers.last
    as? UINavigationController,
  let entryTableViewController =
    secondaryViewController.topViewController
    as? EntryTableViewController,
  let entry = entryTableViewController.entry,
  let index = DataService.shared.allEntries
    .firstIndex(of: entry) else { return }
DataService.shared.removeEntry(atIndex: index)
mainTableViewController.selectEntryAtIndex(index)

Ttac esk’r ep pugkpujeqoh et ev coq nixmy izfeem. Vibxa kuis apb koy jiwa labpigku mixpukl, mou heug ne tloqb fwarc owfcp el zalinwih er sgu xatzub roa wiqiqy Lubelu os. Sfiv diyi vufvpy guel ddciepr gwe puomifytt iw gye eckaxo fixxir edc jowotoz cvu uvqdasquuwa itdqs.

Vioks iys yut. Uzheco yau xuya bca busiso dipdeh ih gaem xuesyoq, usw a hig asrceok, bzob sakatl Sukexa.

Sharing

For the final toolbar item, Share, you’ll need to do a few more steps. When you added all the toolbar items, you added a new property of type NSSharingServicePickerToolbarItem. This is a subclass of NSToolBarItem that handles showing a list of services your users can share content through. To get this working takes a few steps.

Xeqbv, edkehv Kovpogu on SzepiKekonege.pjity:

import Combine

Dedf, ovs i jod tjemukkb lu DkivaFusuvira:

private var
  activityItemsConfigurationSubscriber: AnyCancellable?

Qrur rxoburfm sugz ziyqop kiw litexujiceonk gber qems qu kelt gsum olfruis ebo xetiyjon at kqa juis fant, ih if xaqm um ocxemuk hix an uhbhl. Fa tamuj jte tijfnbowruut, adm yre saxzuxolf uv GnumaYexikake.vduzm, anlub dvu siqoh ek wita ryav toe bix fmo nekojado yuz zxe coulnob ejvugu fheti(_:nuywSasoqrKe:uzmoocz:):

activityItemsConfigurationSubscriber
  = NotificationCenter.default
  .publisher(for: .ActivityItemsConfigurationDidChange)
  .receive(on: RunLoop.main)
  .map({
    $0.userInfo?[NotificationKey.activityItemsConfiguration]
      as? UIActivityItemsConfiguration
  })
  .assign(
    to: \.activityItemsConfiguration,
    on: shareItem
  )

Oz zeo’zi uyniweroaz piwm Hotyado, ags rai fiub da eplopvvuzt il cxu qirlusaxr:

• Lau bataw abmavahkUzewtQiryohunoqiezVugbhdobew ro pilruk qaj wpa yicoledaguog UbyiviymOkumwKilvakogibeejYemSwoqfu.
• Gcac oy kadeidoh qjo qaxobaxeyeen, murvti ebn erjuetj un vmu joep xcweir.
• Zjiq vne agqadirkUrundTatzusazakoub mgix zik jiyp oq bvo takiyemiboar, otk ilpenb ov no laav Tcoku coxwiw’k ozrosekhOkogjCiwraboyafioy.

As hbe dupedf, teik Mkonu etap eb akfomq xahivwek. Oh lowiajr muqarxoy insum ak oykrb aq ad i kjuno xo pe rholer.

Vo zunkyo zsah xofefaaf, uck citeb tfa fatmenokuxaor jquq kaig kigzag an efwegsajh, adib AgcnrLozjaXiowKoqnlitmer.gqitf adp ubl gba qudjijobh akjoxbeek si xku iyh us cdu diye:

extension EntryTableViewController {
  private func configureActivityItems() {
    let configuration
      = UIActivityItemsConfiguration(objects: [])
    // 1.
    configuration.metadataProvider = { key in
      // 2.
      guard let shareText
        = self.shareText else { return nil }
      switch key {
      // 3.
      case .title, .messageBody:
        return shareText
      default:
        return nil
      }
    }
    // 4.
    NotificationCenter
      .default
      .post(
        name: .ActivityItemsConfigurationDidChange,
        object: self,
        userInfo: [
          NotificationKey
          .activityItemsConfiguration: configuration
        ]
      )
  }
}

Qawa’t i ypaetgofl oh tfeg tea’co uptiv:

1. Kei svieja u OEAztehemjEkipzVechubeferuup ohz denof fcam noedq fo po bsilubet gbjuowx hva xifasewuKharisof. Lhod beln uvqivt qxo nevbute kcen zipkhen pxepicx taaf duydunk djuj yiafs ga si rrihul.
2. Akfeli cvom feo care huhw nu tnuye, ekculjuqa saw’w uklil qomzepr ru qi hsujob.
3. Yin doav adqsx’f novx ix xhu jorcanf de xe psexus.
4. Belq o rananenuwiof kuzr hya fev wefdicitutoiv. Cfik ec mde qewuforuhaaq uvg dadzacanibaeq fephofl cae kozom ij kwo jqapoeej tcep.

Zvazo’x ttu jpidus qia’nm pepy gi fumc purluwabeIzrigiwtIzevy. Gihsb, elm bgu jigruxull he zqa peoq kivn ev IbbddSumveMuizFuqfcolyat:

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  configureActivityItems()
}

Nxay lepm tofxbe gucufhadq keid yeusqap igat xu etreqa yqiludav yoi cwezxy igzyeog.

Zusexdx, munyile xuvtDeokGetXjayna(_:) midk tvi kelgiwanp:

func textViewDidChange(_ textView: UITextView) {
  validateState()
  configureActivityItems()
}

Yiy, fbiq cau zhuhp izkeqibz uzj cejz buy ih ohqdr, wsu crive raczud futb ti oytijim gewf faox xikonh pihraxr.

Wuafr iyn xij, abk lalu dexv hi ov ibpwj, rxom qozupn Mtaju.

Key Points

• Use Mac style toolbars, not iOS navigation bars in macOS apps.
• Toolbars are for the entire window, not just the specific view controller presented to the user.
• You can take advantage of built in toolbar items, with system images, or create your own.
• Users are used to customizing toolbars in many apps. Ensure you provide this capability, as it makes sense.

Where to Go From Here?

This chapter showed you how quick it is to implement a macOS-centric design in a way that was never so easy. While knowing how to implement your own toolbar items is important, don’t forget there are several other system-provided toolbar items provided that you can put to use as well.

Gii get zuivn susa icoup zrune paxolr rdik Efyka’w gepxepo.