Creating Interface Builder Palettes with Bindings Support
Volume Number: 21 (2005)
Issue Number: 10
Column Tag: Programming
Creating Interface Builder Palettes with Bindings Support
Palettizing Your Custom NSView Subclasses to Take Advantage of Cocoa Bindings
by
Jeff LaMarche
Introduction
The introduction of Cocoa Bindings back in 10.3 (Panther) was a very well-received addition to
the arsenal of the Cocoa developer, and many of us have begun to use them in our applications
despite the loss of some backward compatibility. Bindings enable us to build applications much
faster than we can without them, and result in much more easily maintained software.
Although Cocoa has an incredible assortment of controls and views for us developers to use when
crafting an application, pretty much every serious Cocoa developer has, at one time or another, had
to create custom views. Sometimes we write custom views of very limited applicability, but sometimes
we create ones that are useful outside of the application they were written for. For the latter
kind, we have the option of creating Interface Builder Palettes out of them, allowing the view to be
easily added to any application's nib file.
Unfortunately, the process of creating a palette, as documented, does not create a palette with
support for bindings. If you open Interface Builder and select an existing palettized view that
you've created, then press ?4 you'll see that the only bindings available to you are the default
NSView bindings of hidden and tooltip. The same is true if you drag a "Custom" view item from the
Containers palette and change its class to your NSView subclass. At first glance, there does not
seem to be an easy way to take advantage of bindings in your custom views.
This month, we're going to walk through the process of creating an Interface Builder palette that
has usable bindings. We're going to create a fairly simple view which draws a gradient. This view
will have two attributes--a start color and a finish color--and we'll create bindings for both of
them. The completed project for this month can be downloaded from the MacTech FTP site.
Setup
Fire up Xcode and select ??N to create a new project, or select New Project... from the File menu.
When the new project assistant window comes up scroll down until you see the category for Standard
Apple Plug-ins, and select IBPalette (figure 1). Name your project MTGradientView. Although it is
generally okay to have spaces in Xcode project names, when using this particular template to create
a new view (as opposed to palettizing an existing view), you should give the project the same name
as the view you plan to create, since the project template is set up to expect that.
Figure 1. Selecting the
IBPalette project template in Xcode.
When the project is open, take a look at it. There's something you should take note of here:
there are two targets to this project, and neither one creates an executable. Since an Interface
Builder palette is designed to be used in multiple applications, the code that makes up the view or
views contained in the palettes get put into a framework and installed in your local Frameworks
directory (~/Library/Frameworks). The additional code and resources that Interface Builder needs,
such as the code and nibs that create the inspector and palette, go into an Interface Builder
palette that gets installed automatically in your local Palettes directory (~/Library/Palettes).
Once you successfully compile a palette project, the palette will become available for your use the
next time you launch Interface Builder.
It's important to understand the way the project is laid out for a couple of reasons. First of
all, if you use the palettized view in an application, any user of your application must have the
framework installed on their machine, or the view will not work. You can handle this in two ways.
Either you can use an installer to install the framework on the user's machine at the same time that
you install the application. The other much more user-friendly and Mac-like way is to embed the
framework right into your application. We'll take a look at how to do that at the end of the
article.
The second reason why it's important to understand the architecture of an IBPalette project
occurs when you want to palettize an existing NSView subclass you've previously written. In that
case, it becomes important to add the class to the correct project target; if you add the NSView
subclass to the palette project instead of the framework project, your plug-in will not work.
Creating a Gradient
Before we code the view, let's create a category on NSColor that will make it easier to draw a
gradient. The code for this category must be included in the framework project. There is no file
template for creating categories, so you can either import the category from the article's project
available on MacTech's FTP site, or use another file template, such as the Objective-C Class or the
Empty File in Project template.
NSColor-interpolate.h
//The header file for our category.
#import <Cocoa/Cocoa.h>
@interface NSColor(interpolate)
+(NSColor *) colorByInterpolatingColor: (NSColor *)color1
withColor: (NSColor *)color2
basedOnProgress: (int)progress
outOfPossibleSteps: (int)steps;
@end
As you see, we're adding a class method to NSColor. This method will create an autoreleased color
based on two existing colors. It will weight the interpolation of the colors based on the last two
parameters. If it's a 10-pixel wide gradient view, and we want the color for the third pixel, we
would pass 3 for the first parameter and 10 for the second, creating a color that is a 30% blend of
one color and 70% of the other. The implementation of the method involves a simple mathematical
interpolation of each of the component of the color and the creation of a new NSColor instance based
on that interpolation.
//NSColor-interpolate.m
@implementation NSColor(interpolate)
+(NSColor *) colorByInterpolatingColor: (NSColor *)color1
withColor: (NSColor *)color2
basedOnProgress: (int)progress
outOfPossibleSteps: (int)steps
{
float red1 = [color1 redComponent];
float green1 = [color1 greenComponent];
float blue1 = [color1 blueComponent];
float alpha1 = [color1 alphaComponent];
float red2 = [color2 redComponent];
float green2 = [color2 greenComponent];
float blue2 = [color2 blueComponent];
float alpha2 = [color2 alphaComponent];
float newRed = red2 + ((float)progress / (float)steps) *
(red1 - red2);
float newGreen = green2 + ((float)progress /
(float)steps) * (green1 - green2);
float newBlue = blue2 + ((float)progress / (float)steps)
* (blue1 - blue2);
float newAlpha = alpha2 + ((float)progress /
(float)steps) * (alpha1 - alpha2);
return [NSColor colorWithCalibratedRed:newRed
green:newGreen blue:newBlue alpha:newAlpha];
}
@end
It's not really important that you understand what's going on in this category in order to
understand how to palettize a view, but this is a handy category to have around.
Creating the Custom View
The project template created an empty subclass of NSView for us already based on the project
name. We know that we need two NSColor instance views, so let's add those to MTGradientView.h, along
with declarations for the mutators and accessors. Creating mutators and accessors whose names
conform to the Key-Value Coding (KVC) naming standard is the vitally important first step in adding
binding support to your view. Fortunately, the KVC naming standard is exactly the same as the
Objective-C instance variable naming convention.
//MTGradientView.h
#import <Cocoa/Cocoa.h>
@interface MTGradientView : NSView
{
NSColor *leftColor;
NSColor *rightColor;
}
- (NSColor *)leftColor;
- (void)setLeftColor:(NSColor *)newLeftColor;
- (NSColor *)rightColor;
- (void)setRightColor:(NSColor *)newRightColor;
@end
Let's also add the implementations of our accessors to MTGradientView.m. You'll notice that in
both mutators, we've placed a call to [self setNeedsDisplay:YES] because we know that changing
either color of the gradient necessarily changes the appearance of the view:
//Accessors & Mutators to add to MTGradientView.m
- (NSColor *)leftColor
{
return leftColor;
}
- (void)setLeftColor:(NSColor *)newLeftColor
{
[newLeftColor retain];
[leftColor release];
leftColor = newLeftColor;
[self setNeedsDisplay:YES];
}
- (NSColor *)rightColor
{
return rightColor;
}
- (void)setRightColor:(NSColor *)newRightColor
{
[newRightColor retain];
[rightColor release];
rightColor = newRightColor;
[self setNeedsDisplay:YES];
}
Now, let's implement the view's drawRect: method.
//drawRect: in MTGradientView.m
- (void)drawRect:(NSRect)rect
{
int i;
NSRect b = [self bounds];
int steps = b.size.width;
for (i = 0; i <steps; i++)
{
NSColor *curColor = [NSColor colorByInterpolatingColor:
[self rightColor] withColor:[self leftColor]
basedOnProgress:i outOfPossibleSteps:steps];
NSBezierPath *path = [NSBezierPath bezierPath];
[curColor setStroke];
[path moveToPoint:NSMakePoint(i,0)];
[path lineToPoint:NSMakePoint(i,b.size.height)];
[path setLineWidth:1.0];
[path stroke];
}
}
That draws the gradient, so... we're done with our view, right?
Nope. In order to create a palette, the view must also implement initWithCoder: and
encodeWithCoder: so that it can be serialized into the nib file. Let's replace the stub
implementations of initWithCoder: and encodeWithCoder: with real ones. Interface Builder is capable
of creating nibs using either an NSArchiver or an NSKeyedArchiver, so we'll add support for both
methods of archiving, even though the use of NSArchiver has been deprecated:
//Serialization methods for MTGradientView.m
- (id)initWithCoder:(NSCoder *)coder
{
self = [super initWithCoder:coder];
if (self)
{
if ([coder allowsKeyedCoding])
{
[self setLeftColor:[coder
decodeObjectForKey:@"leftColor"]];
[self setRightColor:[coder
decodeObjectForKey:@"rightColor"]]
}
else
{
[self setLeftColor:[coder decodeObject]];
[self setRightColor:[coder decodeObject]];
}
}
return self;
}
- (void)encodeWithCoder:(NSCoder *)coder
{
[super encodeWithCoder:coder];
if ([coder allowsKeyedCoding])
{
[coder encodeObject:[self leftColor]
forKey:@"leftColor"];
[coder encodeObject:[self rightColor]
forKey:@"rightColor"];
}
else
{
[coder encodeObject:[self leftColor]];
[coder encodeObject:[self rightColor]];
}
}
Adding Bindings
We've already done most of the work needed to support bindings in our view, which was to create
KVC-compliant mutators and accessors. There's one other step we need to take in order to let
Interface Builder know what bindings our view supports: We have to "expose" the bindings. This is
done by overriding NSObject's initialize method, which gets called before any objects are
initialized. In that method, we have to call another of our class' class methods named
exposeBinding: for each binding that we want to expose.
//initialize method in MTGradientView.m
+ (void)initialize
{
[self exposeBinding:@"leftColor"];
[self exposeBinding:@"rightColor"];
}
Clean Up
The last thing we have to do to our view before we can create a palette out of it, is to release
our two instance variables by overriding dealloc.
//dealloc method in MTGradientView.m
- (void)dealloc
{
[leftColor release];
[rightColor release];
[super dealloc];
}
Create the Palette
Now that we have a serializable view, we need to create a palette for it. The palette is a panel
that will get added to the Interface Builder palettes (figure 2). Expand the Palette folder, then
inside that expand the Classes folder and single-click on MTGradientViewPalette.h. We need to add an
IBOutlet instance variable so that we can access our view from the palette.
//MTGradientViewPalette.h
#import <InterfaceBuilder/InterfaceBuilder.h>
#import "MTGradientView.h"
@interface MTGradientViewPalette : IBPalette
{
IBOutlet MTGradientView *view;
}
@end
@interface MTGradientView (MTGradientViewPaletteInspector)
- (NSString *)inspectorClassName;
@end
Next expand the Resources folder, double-click on MTGradientViewPalette.m and wait for Interface
Builder to open up.
Figure 2. Interface
Builder's palettes. Here, the built-in Controls palette is currently selected.
Once Interface Builder is open and ready to go, drag MTGradientView.h over from XCode to
MTGradientViewPalette.nib's main window and then drag MTGradientViewPalette.h over as well. This
will let Interface Builder know about the changes we've made to these two header files. Double-click
the icon called Palette Window to open up the window (if it's not already open). This "window" will
not actually appear as a window, but rather its content pane will become part of the Interface
Builder palette.
Now switch to the Containers palette (figure 3) and drag a custom view (the lower left item) over
to the palette's window. You can make it any size you want, but since it's the only view we're going
to have in our palette, you might as well have it take up most of the space.
Figure 3. The Containers
palette.
Now single-click the custom view you just added and press ?5 to bring up the view's custom class
inspector. Change the selected class from NSView to MTGradientView.
Figure 4. The completed
palette window.
Single-click on the File's Owner icon and change the selected class for the file's owner to
MTGradientViewPalette. Control-drag from the File's Owner icon to the MTGradientView in the palette
window and connect it to the view outlet we created earlier. Save and go back to Xcode. You can
leave Interface Builder open if you want; we'll be back in a few minutes.
In Xcode, single-click on MTGradientViewPalette.m. We have an opportunity, by overriding the
method finishInstantiate, to initialize the parameters of our NSView. This will allow us to dictate
how the view will appear when drawn in Interface Builder. Let's set our view to draw a gradient from
red to blue when displayed in Interface Builder. The project template created a stub implementation
of the finishInstantiate method; go ahead and add the code in bold to the existing stub.
//finishInstantiate in MTGradientViewPalette.m
- (void)finishInstantiate
{
[view setLeftColor:[NSColor blueColor]];
[view setRightColor:[NSColor redColor]];
}
An Inspector
At this point, we could use our palette, provided that we wanted to only use bindings. But we
really should add an inspector to allow the user to change the two color attributes. The attribute
inspector is the floating window that appears when you type ?1 in Interface Builder where you can
set initial values for the currently selected control or item. We'll create an inspector using the
other class and nib file created for us. Single-click on MTGradientViewInspector.h and let's add
IBOutlet methods for the two color wells our inspector will need.
//MTGradientViewInspector.h
#import <InterfaceBuilder/InterfaceBuilder.h>
@interface MTGradientViewInspector : IBInspector
{
IBOutlet NSColorWell *rightColor;
IBOutlet NSColorWell *leftColor;
}
@end
Double-click on MTGradientViewInspector.nib, which should open up in Interface Builder. Before we
proceed, drag MTGradientViewInspector.h from Xcode over to the newly-opened nib window to tell
Interface Builder about our new outlets. Single-click on the File's Owner icon, and press ?5 to
bring up the custom class inspector. Change the File's Owner's class to MTGradientViewInspector.
Next, add two color wells from the Controls palette to the inspector window. You should also add
labels to tell the user which is the left and which is the right.
Figure 5. The completed
inspector window.
Now, we need to connect the two color wells we just added to our inspector's class' NSColorWell
outlets. We can do this by control-dragging from the File's Owner icon to each of the color wells,
connecting them to the appropriate outlet. Also control-drag from the File's Owner icon to the
Inspector Window icon, and connect it to the window outlet. Save and this time, quit right out of
Interface builder before going back to Xcode.
Back in Xcode, single-click on MTGradient ViewInspector.m. In this class, there are two methods
that we need to implement; the project template has already given us stub implementations of both of
them. In the ok: method, we need to take the values from our inspector and put them into the view.
In our case, that means we need to take the colors from the two color wells and provide those values
to our gradient view. In the revert: method, we have to take the attributes from the view and put
them back into the controls. In our case, that means taking the colors from the view and setting the
color wells based on them. Doing this is relatively straightforward code, once you know that you can
get a reference to the view being edited by calling [self object]. You can leave the init method
alone; it is fine just the way the template created it.
//MTGradientViewInspector.m
- (void)ok:(id)sender
{
MTGradientView *selView = [self object];
[selView setLeftColor:[leftColor color]];
[selView setRightColor:[rightColor color]];
[super ok:sender];
}
- (void)revert:(id)sender
{
MTGradientView *selView = [self object];
[leftColor setColor:[selView leftColor]];
[rightColor setColor:[selView rightColor]];
[super revert:sender];
}
Guess what? Our palette is now functional. Go ahead and compile using the MTGradientView or All
target, then open up Interface Builder. In the list of palettes, there should be a new one called
MTGradientView. Select it, and voila! There it is. Isnt' it purty?
Figure 6. The completed
palette in action inside Interface Builder.
You can drag MTGradientViews from the palette onto application windows exactly like you do with
the built-in palettes. You can set the view's initial color values in the attributes inspector and
you can bind both leftColor and rightColor just as you would the bindings of any of the delivered
controls. Pretty cool, huh?
Figure 7. The gradient
view's bindings.
The only real problem with using this view is that the code for producing the view is external to
your application contained in a framework in your home directory. That means that your application
will not work on other machines unless you install that framework on their machine.
Making the Framework Embeddable
The solution to this problem is relatively simple: Make the framework embeddable. Go back to
Xcode and expand the Targets group in the Groups & Files pane. You should see three targets: one for
the MTGradientView, one for the MTGradient ViewFramework, and one called All. Single-click on the
MTGradientViewFramework target, then right-click (or control-click if you're old-school and using a
one-button mouse) and select Duplicate from the contextual menu. This will create a new target
called MTGradientViewFramework Copy; rename it to MTGradientViewFramework Embed.
Because Interface Builder needs access to the framework, we have to keep the original target so
that the framework gets built and installed to the local frameworks directory where Interface
Builder has access to it. But we also want to build an embeddable version that doesn't get
installed. Single-click the new target if it's not already selected, and press ?I to bring up the
target inspector. Click on the Build tab and select deployment on the Collections popup menu.
One of the options under the deployment collection is Skip Install. Click the checkbox next to it
so that it becomes checked. This will stop this target from installing the framework created by this
target. Next, we need to change the value of the Installation Directory to a special value that will
allow it to be embedded. Change it to read @executable_path/../Frameworks (see Figure 8).
Figure 8. The deployment
setting for the embedded framework target.
Drag the new target over onto the All target, which will cause your new target to get built when
someone builds all targets. Now, if you compile with either the new target or the All target and
look in the project's build folder, you will see a new folder called UninstalledProducts. Inside
that folder is the embeddable version of your framework.
Embedding the Framework
You can now create applications that include the MTGradientView functionality right inside the
executable, which means no annoying framework installation for your users. Let's take a look at how
you go about doing this, as it involves a bit more than simply including the framework in your
application project. Create a new project in Xcode using the Cocoa Application project template, and
call it MTGradientViewTester. Once the project is open, right-click on the Frameworks group and
select Add?Existing Frameworks...
When the standard open sheet comes up, navigate to the UninstalledProducts folder of the palette
project's build folder and select the MTGradientViewFramework.framework file. Now, expand the
Targets group and expand the MTGradientViewTester target. You'll see three build phases in there. We
need to add a fourth. Select the MTGradientViewTester Target and select New Build Phase?New Copy
Files Build Phase from the Project menu. Single-click the new build phase that you just added and
press ?I to bring up its inspector.
On the inspector for the build phase, you'll see a pop-up menu called Destination. Change the
value of that pop-up to read Frameworks, which tells this phase to copy its contents to the
Frameworks directory of the application bundle. Now drag the MTGradientViewFramework.framework from
the Frameworks group to this new copy phase. If the drag worked, the name of the copy phase should
change from Copy Files to Copy Files (1).
The End
That's it. The framework is now embedded and you can build deployable applications using the
gradient view we just palettized! And best of all, every time you build your application, it will
embed the most current version of the MTGradient ViewFramework. Go ahead and try adding an
MTGradientView to this application's nib file. Try binding it to variables, and binding NSColorWells
to the same variables. I'm not going to walk you through building the tester application, as it's
pretty straightforward, but in the article's source code available from the MacTech FTP site, I've
included a complete tester app that shows how to use bindings with the custom view we created. The
tester application allows you to change the gradient by changing the left and right color with color
wells.
Jeff LaMarche wrote his first line of code in Applesoft Basic on a Bell & Howell Apple
//e in 1980 and he's owned at least one Apple computer at all times since. Though he currently makes
his living consulting in the Mac-unfriendly world of "Enterprise" software, his Macs remain his
first and greatest computer love. You can reach him at jeff_lamarche@mac.com.
