Original URL: http://www.theregister.co.uk/2008/10/14/mac_secrets_imagekit_internals/

Apple's ImageKit exposed

Inside view

By Dave Jewell

Posted in Developer, 14th October 2008 17:01 GMT

Mac Secrets When Leopard arrived, a number of significant new technologies came with it, including Objective-C 2.0, Core Animation, and ImageKit.

ImageKit brings together a number of classes designed to make it easy to display and edit images, view slideshows, take pictures using an attached or built-in camera, and more besides. In fact, ImageKit is itself built on top of Core Animation, hence the snazzy effects that it uses. The latest version of Preview also makes use of ImageKit when displaying and manipulating images.

This all sounds great and doubtless gets you straining at the leash to start working with the ImageKit classes, right? Unfortunately, there are some intriguing holes in the documentation. These piqued my interest.

The IKImageView class is designed (as the name suggests) to implement image viewing along with simple editing capabilities. It's easy to configure an instance of this class so that double-clicking the image view brings up a standard edit panel, from where the user can adjust things like gamma, saturation and brightness, as well as applying assorted Core Image filters.

Problems arise, though, when you start trying to really use IKImageView in anger, and - yes - anger could well be part of your experience. For example, the documentation states you can assign a delegate to IKImageView, but completely avoids telling you what delegate methods to respond to. Here's what you get:

An IKImageView object's delegate is inserted in the responder chain after the image view itself and is informed of various actions by the image view through delegation messages.

Helpful? There's no indication of what actions we're talking about, or what messages are sent to the delegate. In fairness to Apple, the lack of documentation is probably due - in part - to the complexity of the ImageKit framework.

If you've done much programming with Core Animation, you'll know that different layers sometimes field different messages. And in the same way, the architecture of ImageKit means it's not just the IKImageView class itself that gets to talk to the delegate object you supply.

So what delegate methods are available? The following methods are implemented directly by IKImageView.

- (void) selectionRectAdded: (IKImageView *) imageView;
- (void) selectionRectRemoved: (IKImageView *) imageView;
- (void) selectionRectChanged: (IKImageView *) imageView;
- (void) imagePathChanged: (NSString *) imagePath;

As you'll infer, the first three delegate methods are triggered when the current selection rectangle changes: This implies you're using a relevant tool mode such as IKToolModeCrop or IKToolModeSelect. The fourth method is triggered whenever the image path changes such as - for example - when the user drags a new graphic onto the image view. This is useful because the full path is supplied as a parameter, but it's annoying that the relevant image view instance isn't returned.

Strictly speaking, those are the only delegate methods supported by IKImageView, but - like I said - other classes can potentially get in on the act. An internal class (IKComposer, if you're curious) will also examine the specified delegate object to see what delegate methods it supports. At this point, I'd like to thank Jim Turner for giving me a pointer on this one. Jim's a Cocoa Mac programmer from Iowa who I met and have been talking to on an Apple mailing list for Cocoa developers.

The delegate methods discovered by Jim are:

-(void) imageWillChange: (IKImageView *) imageView;
-(void) imageDidChange: (IKImageView *) imageView;
-(void) imageDidChange: (IKImageView *) imageView 
           imageState: (IKImageState *) state
image: (CGImageRef) image;  
- (NSUndoManager *) undoManagerForOperation: (NSString *) operation;

If your delegate responds to the more complex imageDidChange: method, then the simpler one will never be called: The two are mutually exclusive. For more information on IKImageState and IKComposer, use class-dump. Jim and I have discovered that imageWillChange: is always called reliably, but this isn't necessarily the case for the imageDidChange: variants.

NSImageView

IKImageView, and more, can be found inside Apple's latest Preview

Delegate methods aside, there are plenty of other interesting aspects to IKImageView. Use these methods to get a checkerboard background in your image view:

- (BOOL) showsCheckerboard;
- (void) setShowsCheckerboard: (BOOL) showsCheckerboard;

As mentioned earlier, double-clicking on an IKImageView will invoke the image-editing panel. One quirk of the image-editing panel is that it stubbornly refuses to go away when you switch over to another application.0 If - like me - you don't like this behaviour, you can fix it using the code below:

[[IKImageEditPanel sharedImageEditPanel] setHidesOnDeactivate: YES];

Another interesting feature of IKImageView is the tool mode. Apple document a number of tool modes, but in addition to the official modes, I've also discovered those below:

IKToolModeSelectEllipse
IKToolModeSelectLasso
IKToolModePaste*

It's pretty obvious from the names what these do. Bear in mind that IKToolModePaste is somewhat unusual - hence the star. You can't set this tool mode in the normal way using the setCurrentToolMode: method.

Finally, a number of folks have pondered the easiest way of getting an NSImage into an IKImageView. The documentation states you can use an NSImage, but the official setImage:imageProperties: method expects a CGImageRef. So, what to do? It turns out that Apple neglected to document another method called, simply, setImage:. Just pass an NSImage to via setImage, and you're good to go.

[_myImageView setImage: [NSApp applicationIconImage]];

There's no demo application this week to show undocumented aspects of IKImageView and other classes lurking inside ImageKit so no homework for you. Hopefully, though, you've got a taster for what IKImageView can do for you. ®