I can't tell you how good your timing is for this series - I've recently started Cocoa development and already have a rather daunting project on the boil.

Any chance of a specific feed/email alert for this series? I don't want to miss any but I also don't need all the new hardware stories to remind me how inadequate my old MacBook is.

So where are all the people who post complaining about poor Apple documentation?

'there are an amazing number of undocumented wheels within the Apple libraries'

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

It's either OK for all, or OK for none - not it's OK as long as you're not MS

...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?

"""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.

Nexox: "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."

Tell me you're kidding? Microsoft has been found guilty of doing PRECISELY the same thing. Not all the undocumented API's that Microsoft has been forced to publish were to do with communications and protocols and interop etc.

Apple has as much of a monopoly for software that runs on their proprietary machinery as Microsoft has claimed to be on standard PC gear. Actually, they have a proportionally far bigger monopoly on software that runs on their OS than MS has on Windows.

So why are they not held to the same standards and forced to publish and support a large number of the API's that they've written and included in their OS that give Apple an advantage *ON THEIR OS* that they don't offer to other app developers who target that platform?

Personally, I would recommend avoiding the use of undocumented API's wherever possible because the minute you embed use of said API into your app and ship it, you have a support nightmare on your hands ... it's only a matter of time until a new version of the OS is released that removes or changes the API and busts your app.

Hey El Reg guys ... you REALLY need to add a Jobs with halo and Jobs with horns icon too. Just be sure they're big horns.

Paris because at least she documents all of her interfaces! ;)

"but nobody really wants to use OS X for anything"

Erm... that came across as a rather sweeping statement. Can you please explain what you mean?

FYI: approximately 60% of my company's customer base is running OS X, and the rest are saving up for a Mac. It's just the nature of the music technology sector.

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

2.4Mb of which 90% is redundant pbindex files isn't a good start.

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

Dave

This is an extremely stupid thing to do. You can already write Prefs panes, starting with the Preference Pane template in Xcode, and you can access a users' preferences database with published API. See the NSUserDefaults and NSUserDefaultsController classes.

When you use undocumented methods, you make your apps fragile and you're opting out of getting any support.

-jcr

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.

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

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

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".

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

Having to support code that uses private classes is soul destroying - as every apple update becomes cause for panic...

If the remainder of your articles also involve private classes then I strongly recommend you devote your next article to discussing runtime checks so that code that uses private classes/code can 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