Saturday, March 20, 2021

Theme Compliant Preferences for Big Sur and below

How to adapt your Preferences Window toolbar so it looks and works like an Apple app on macOS Big Sur and consistent with previous OS Versions.

Saturday, March 20, 2021 - Sam Rowlands

A common question I get asked, is how to make a Preferences Window look and work consistently with macOS Big Sur, while still looking and working consistently with older versions of the macOS.

Preferences Dialog in macOS Big Sur

Preferences Dialog in macOS Mojave

Start with the toolbar

Layout the toolbar in the Xojo IDE, adding only the buttons to use for switching the pane. Make sure all the buttons are "ToggleButton" in the IDE. You can specify icons here, but they'll be overwritten when running on Big Sur, so I personally don't bother.

Add some code

The following code uses the Ohanaware App Kit, but you should be able to translate it to whatever application kit that you're using. Place it in the "Open" event of the window.

The property "app.fullColorIconsUse" allows my users to choose between Big Sur consistency or easily recognizable icons.

The code works by using NSArrayObjectAtIndex( items, 0 ) to get the toolbaritem, NSControlSetImage then sets the image on the item. NSImageFromName will load images from either the system or that are contained in the Resources folder of the application, while NSImageWithSymbolName will use a SF Symbol as the image. SF Symbols only work on macBS or newer.

#if targetMacOS then
  Dim tHandle as integer = NSWindowToolbar( self.handle )
  Dim items as integer   = NSToolbarItems( tHandle )

  if operatingSystemisAtLeastBigSur then
    // If we're on macBS, tell the window to use the Preference style toolbar.
    NSWindowSetToolbarStyle( me.handle ) = NSWindowToolbarStyleValue.preference
  end if
  
  if app.fullColorIconsUse or operatingSystemisAtLeastBigSur = false then
    // --- If the user has choosen full color icons or is running on an older version of the macOS
    NSControlSetImage( NSArrayObjectAtIndex( items, 0 ) ) = NSImageFromName( "NSImageNamePreferencesGeneral" )
    NSControlSetImage( NSArrayObjectAtIndex( items, 1 ) ) = NSImageFromName( "NSImageNameUserAccounts" )
    NSControlSetImage( NSArrayObjectAtIndex( items, 2 ) ) = NSImageFromName( "interfaceIcon" )
    
  else
    // --- macBS, so use SF Symbols.
    NSControlSetImage( NSArrayObjectAtIndex( items, 0 ) ) = NSImageWithSymbolName( NSImageClass, "gearshape", "general" )
    NSControlSetImage( NSArrayObjectAtIndex( items, 1 ) ) = NSImageWithSymbolName( NSImageClass, "person.crop.circle", "accounts" )
    NSControlSetImage( NSArrayObjectAtIndex( items, 2 ) ) = NSImageWithSymbolName( NSImageClass, "macwindow.on.rectangle", "Window" )
    
  end if
#endIf

Finally...

You need to mark your Xojo made application as BS compatible, to do that you currently need to use App Wrapper.

If you don't have an active license plan for App Wrapper, you can always take advanatge of the 14-Day trial by downloading it from ohanaware.com/appwrapper/aw4.html