A better way to build OS X preferences

The rant area is down the hall...

...on the left, and at the end of the very short plank.

All operating systems have undocumented features... we all hate writing documents that's why we have things like JavaDoc and Doxygen to help us think it's not like documentation, but more like coding. "Use the source, Luke" Now if we could just get access to the source :-D

Nice brief article... through didn't explain to me why? Though i am assuming this is we can build prefs that look more like Apple layout?

Re: OK for some but not others?

"""So it's OK for Apple to do it, but the whole world is up in arms when MS do it?"""

People keep saying things like this, and the key that they don't realize is that MS doesn't make an operating system or a mail server. They make (or try to make) an entire environment, from OS to office apps to web and sql servers. They try to engineer it so that if for some unholy reason you need exchange server, you need eveything else they sell too. And their mechanism for locking out competition is to prevent people from using their proprietary APIs.

Sure OSS and Apple don't document everything, but nobody really wants to use OS X for anything, and if you need OSS APIs badly enough, dig into the source for a while (Feel free to share your results and document along the way.)

I suspect that Apple wants to keep their apps visually seperated from 3rd party apps, so they hide some of the GUI calls they use. Thats not particularly nice, but its also not completely anti-competitive.

In summary, it's never really acceptable to have undocumented APIs, but its really, really bad to do it to keep millions of people locked into your crap software. Which is why people get so pissed at MS.

My take....

Thanks for the comments so far guys. My take on this is that Apple shouldn't leave undocumented those features which application developers are >>obviously<< going to need. The ability to create preference panes is just such a feature.

There is obviously going to be low-level nastiness that the average developer shouldn't need to touch, except in very rare circumstances but -- heck -- preference panes ain't exactly rocket science. To me, they're a core part of the Mac user experience.

Dave

RE: Thank You!

Thanks for the kind comments, Charles. We plan to publish a Mac Secrets article once a month, so keep checking back.

Dave

2 Bonehead moves in 1!

So you're going to use undocumented APIs--which means they are APIs that aren't ready for prime time--and accomplish two bonehead moves in one fell swoop:

1. You don't even get notifications if these things change, introducing the possibility of subtle bugs in any app in which you use them, effectively creating an app that no one in their right minds would consider using if the app stores or creates valuable user data.

and the big one:

3. You write a help column and suggest that people consider going waaaay off Interface Guidelines in making an app's preferences look like the System Preferences.

(yeah, sure it's just an example, but if this code was really useful, you'd have a useful example.)

Good job you.

Homework for Dave Jewell: find a use for NSPreferences in any place where it wouldn't violate HIG.

RE: 2 Bonehead moves in 1!

Hi Jeff. You have also misunderstood the article. Perhaps you've been talking to Mr. Randolph? ;-)

Do you think the program preferences in (e.g.) Apple Mail look like System Preferences? No? Me neither. But by your way of thinking, they should, because Mail uses NSPreferences.

Please reread the article and run the sample app.

I won't discuss the use of undocumented API's here because I cover it in the article. I'll just say that if Apple bothered to document them, they wouldn't be undocumented! ;-)

Dave

RE: Bloody Stupid

Hi John. As I've already pointed out to you via email, my article discusses the preference windows that an application displays when you choose "Preferences..." from that application's menu.

The XCode template you're referring to is used to create a preference pane (file extension ".prefPane") that's dynamically loaded and displayed by the System Preferences application.

They are two completely different things.

You have misunderstood what I was writing about.

Dave

Listening to Mr. Randolph

Dave,

YOU should be listening to John Randolph. I wish there were a hundred John Randolphs out there to help people with Cocoa and Objective C.

There are reasons why private APIs are still private: they're NOT READY FOR PRIME TIME. Unless, of course, you want shitty, substandard APIs releases, then repaired, then required to be dragged along into the future for 5 or 10 years?

Do you know what Image Kit is? Does it look a little familiar? Guess what its history was.

Apple can release a fix to NSPreferences ALONG WITH a new relelase of Mail.app.

If you've never developed APIs for mass consumption, you can be the best engineer in the world and still not understand the caution that must be employed before releasing them.

if you really knew what you were doing with private APIs, employing them should also come with big orange traffic cones around them in your code.

You DO know about dynamic runtimes, right? If you do, you should know how to implement those "orange cones" around calls to undocumented APIs. How come you didn't mention that safeguard?

And why would you go digging in private APIs for this when all you need is an NSToolbar and an NSTabView? You could do far more of it in IB (always better if you can do things there) and avoid being broken in the future?

In my opinion, NO ONE new to Cocoa should be taking advice from this column. Using private APIs is dangerous, stupid and destined to make Mac software overall less stable and less "like a Mac".

RE: Listening to Mr. Randolph

Hi Jeff. Thanks for the comments. As I'm sure you're aware, I had a protracted email chat with John. I got the standard argument that the class isn't ready for prime time. This, despite the fact that Apple's production applications (Mail/Safari) have been using it for years!!!

I can't quite figure out why a class is ready for prime time if an Apple application is using it, but it's not ready for prime time if anybody else wants to use it? Weird, don't you think? ;-)

Dave

Re: fail gracefully

Hi AC. I wouldn't disagree with that. As should be obvious, if you're gonna use undocumented features, then you should do your best to get your app to fail gracefully if Apple change the goalposts.

E.g. use "respondsToSelector:" to check for the presence of undocumented methods, NSClassFromString to check for the presence of undocumented classes, etc.

I didn't put this into my article because (a) I have a very tight word count of 800 words and (b) it should be obvious that this column isn't for noobs. Maybe I should devote a column specificially to bullet-proofing....

Cheers,

Dave