How can I make an "appearance file" for NSAppearance?

Question

I was reading the Cocoa documentation and stumbled across some new features in the 10.9 API.

From the docs I gather that the NSAppearance class and a related protocol NSAppearanceCustomization Appear to be a means of customizing the appearance of NSView and its descendants.

An NSAppearance object represents a file that specifies a standard or custom appearance that applies to a subset of UI elements in an app. An app can contain multiple appearance files and—because NSAppearance conforms to NSCoding—you can use Interface Builder to assign UI elements to an appearance.
Typically, you customize a window by using Xcode to create an appearance file that contains the views you want to customize and the custom art that should be applied to them. Xcode transforms the file’s art content into a runtime format that AppKit can draw when the specified views are displayed.

Well that all sounds neat and promising, but nowhere in the documentation can I find what an appearance file is or how to make one. Google searches are coming up empty other than for the thin documentation I have already read.

I do see that UIKit has a similar sounding UIAppearance class, but from what I can tell this is not a straight port of the UIKit class.

Does anybody know how to make one of these magic "appearance files" and what exactly we can do with them?

Answer 1

There is a private framework called "CoreThemeDefinition" which handles uicatalog files, these files can be turned into ".car" files and loaded using NSAppearance. I personally think Apple is going to include an editor in Xcode in the future, but for now you can use this little tool I've made: https://github.com/insidegui/AppearanceMaker

You first open the app and select a place to save the uicatalog file, then you click "create skeleton". This will export various PSDs containing the default images for the controls, you can then edit them, save and export the car file using the app.

This file needs to be included in your app's resources, and you load this custom appearance using:

[[NSAppearance alloc] initWithAppearanceNamed:@"Your-appearance-name" bundle:nil]

Answer 2

EDIT: Guilherme's response is more accurate, although there is still no public way of altering appearances like you can in iOS.

NSAppearance isn't much like UIAppearance (from what I can tell), it only relates to having controls under normal or light colored appearances. An example of this would be when you draw into a popover (light) vs a window toolbar perhaps (normal), NSAppearance allows you to identify which environment you're drawing into. To be honest I haven't used it yet, but the most information I've found was in the WWDC 2013 video on What's new in Cocoa and the 10.9 release notes

From my understanding, it allows you to specify what the control looks like on a particular background. If a control you use is to be reused on a different background, you could check the current appearance and draw your control accordingly using [NSAppearance currentAppearance]

Another important part is that there is a new protocol your views or windows can adopt called the NSAppearanceCustomization protocol which allows you to specify that view's appearance. Not exactly sure how this works but it's there. Some Cocoa control also have these implemented which are discussed in the HIG for Controls.

There are 2 appearances that Apple defines but you might be able to define your own using your own strings (again, not sure). At the bottom of the docs you linked to you'll find these 2 constants:

APPKIT_EXTERN NSString *const NSAppearanceNameAqua;
APPKIT_EXTERN NSString *const NSAppearanceNameLightContent;

So it's no UIAppearance, it's just a way of knowing what type of background you're drawing onto.