Mac Secrets Welcome my second “peek behind the scenes” for Cocoa developers. I enjoyed the responses to the first installment, both for and against, and especially the lively email exchanges, some of which I plan to pick up on in the near future!
For now, though, let me just emphasize a couple of important points.
First, this column is not for novice Cocoa developers. If you're new to Cocoa programming, then you definitely shouldn't be casually exploiting undocumented features of the platform. Instead, go check out some of the great Cocoa tutorials here.
Next, when working with undocumented classes and methods, be sure to bulletproof your code as much as possible. As one of my respondents said: “It's important to have your code fail gracefully if a wanted class/method doesn't exist, rather than... uhh... disgracefully!”
To put this in concrete terms, before calling an undocumented method, use the respondsToSelector: message to see if the method exists. Similarly, when checking for the presence of an undocumented class, use NSClassFromString to get a reference to the wanted class. If the returned reference is nil, then you know the class no longer exists.
You won't find these checks in my sample project because I don't want to obfuscate the basic intent of the code and we all have our own ideas about how error handling should work.
Things get slick
Having got the compulsory caveats out of the way, let's take a look at how to implement the so called "media browser" feature inside your own application. As the name suggests, a media browser is designed to let the end user browse for media - meaning things like photos, movies and audio files - before selecting a wanted item and incorporating it into their document.
Browse before selecting your media
At time of writing, a number of open-source media browser implementations exist. For example, type "iMediaBrowser" into Google, and you'll be pointed at various different projects. Heck, you can even buy a commercial implementation. The most popular browser, however, is totally free, includes full source code and it's available here. Once you've downloaded the code and looked through it, you'll see that it's quite a complex beast, using an extensible architecture to handle various different media types.
With free media browsers available, why use the undocumented Apple one? Well, aside from the fact that it's also free, the Apple media browser has a few additional strings to its bow. One big advantage is that the Apple browser supports the Events feature recently added to iPhoto 7. As far as I know, no other media browser supports this, meaning that photo browsing is much less convenient.
So how do you make use of the Apple browser? This turns out to be simplicity itself. Create a new, windowed, Cocoa application project in Xcode, and drag Apple's private iLifeMediaBrowser.framework into the frameworks section of your project window. You'll find it hiding inside /System/Library/PrivateFrameworks. Now edit your MainMenu.nib file by adding a custom view to it in the usual way. Use Interface Builder's Inspector window to change the custom view's class name to ILMediaBrowserView. Now save and run your application. Voila - you've got an instant media browser!
Didn't work for you? Chances are you're not running Leopard. Apple added the iLifeMediaBrowser framework to the 10.5 SDK, but it's not a part of the 10.4 SDK. Yes, it's perfectly possible to use the Apple Media Browser without problems under Tiger, but it involves a few more wrinkles than there's room to discuss here. Instead, let's look a little deeper at the ILMediaBrowserView object.
By default, the browser operates in audio mode - meaning you'll see a list of all your iTunes albums, podcasts and other media in the usual format. I've added a little code to the demo program to illustrate how to switch modes for photo browsing or movie browsing. As mentioned earlier, when you're browsing photos, you'll see a list of defined iTunes events. If you don't want to use the setCurrentBrowserType: method, there are three distinct methods which switch between the wanted modes as below:
- (void)displayAudioBrowser:(id)sender; - (void)displayImageBrowser:(id)sender; - (void)displayMovieBrowser:(id)sender;
All the other available methods are included in ILMediaBrowserView.h, which is included as part of the project. As ever, I used the class-dump utility to create this header file. You'll see that there are a number of options here for customising the appearance of the browser. For example, setTableAlternatingRowColors: can be used to set custom colors for table rows when displaying media:
[_browser setTableAlternatingRowColors: [NSArray arrayWithObjects: [NSColor colorWithCalibratedWhite: 0.2 alpha: 0.8], [NSColor colorWithCalibratedWhite: 0.25 alpha: 0.8], nil]];
Personally, I would be strongly disinclined to mess with that stuff because the last thing you want is to confuse the end user with a weird-looking media browser. If you're planning to embed the browser in a HUD window, though, then some judicious customization would make sense.
In case you're wondering how to actually select media in an application, the answer of course is drag and drop. I've added an editable NSImageView control to the demo program to illustrate the point. More typically, you'd build the image browser into a panel, and drag from there into the main document window. The demo program can be downloaded from here.
Have fun with the Apple media browser. More undocumented naughtiness next time.®