Cocoa Dev Central

Intro to Quartz II
This tutorial is the second entry in the Introduction to Quartz series. Intro to
Quartz Part I describes ideas that are essential to understand before reading this
tutorial. Even if you've read it, you may want to review first.

This tutorial explains how to create and use custom views, how to construct paths
using NSBezierPath, and touches on a variety of topics related to using images
with the NSImage class.

This tutorial is written and illustrated by Scott Stevenson

Copyright © 2006 Scott Stevenson

Custom Views
A custom view is a subclass of NSView which serves a "blank canvas" for your
drawing code. Once you have created the view class, you add drawing code using
rects, paths and images in the drawRect method.

To create a new view class in your project, choose File > New File in Xcode and
select Objective-C NSView subclass

After the class file is created, you drag the header file to the NIB window in
Interface Builder so it knows about the class.

Now the class has been added to the NIB file and can be used in a custom view.
Using a Custom View
Once the view has been added to the NIB file, open the Interface Builder palette
and drag the CustomView icon out onto your application window.

While the custom view is still selected, bring up the inspector and choose MyView
from the Custom Class inspector dropdown.

The custom view now uses the MyView class. You should also select Size from the
inspector dropdown at this point to configure the sizing to your liking.

The view will not display anything until drawing code is added to drawRect method
in the MyView class.

In the above screenshot, we added a 210x210 rect and filled it using a blue
NSColor.

We implemented isFlipped to return YES so that the coordinates start in the upper-
left instead of the bottom-left.
Paths
Rects can be used for basic graphics, but paths allow for much more complex
shapes. The NSBezierPath class is used to create paths in Cocoa.

Paths are mutable, so they can be changed or combined at any time. Path objects
can draw themselves into a view. Here are some examples:

Paths can contain curved lines, arcs and rectanges. Each of these examples were
drawn to the view by sending the stroke message to the path object.

To create a curved line, you provide a start point, and end point, and two
"control" points which act as gravity on the line shape. Control points are not
needed for simple straight lines.

Filled Paths
Paths can be filled in addition to being stroked. The following examples first use
the fill method with a white NSColor set, then stroke the path with a gray color
set.

The paths are filled before being stroked so that the lines are visible.
Creating Paths

The following examples show how to create paths. All of the code assumes a flipped
view with coordinates starting in the upper-left.

NSBezierPath * path = [NSBezierPath bezierPath];

[path setLineWidth: 4];

NSPoint startPoint = { 21, 21 };

NSPoint endPoint = { 128,128 };

[path moveToPoint: startPoint];

[path curveToPoint: endPoint

controlPoint1: NSMakePoint ( 128, 21 )
controlPoint2: NSMakePoint ( 21,128 )];

[[NSColor whiteColor] set];

[path fill];

[[NSColor grayColor] set];

[path stroke];

Here's an example of appending a path to an existing path. The path being added is
an arc:

NSBezierPath * path = [NSBezierPath bezierPath];

[path setLineWidth:4];

NSPoint center = { 128,128 };

[path moveToPoint: center];

[path appendBezierPathWithArcWithCenter: center
radius: 64
startAngle: 0
endAngle: 321];

[[NSColor whiteColor] set];

[path fill];

[[NSColor grayColor] set];

[path stroke];

It's also easy to create a bezier path from a basic rect:

NSPoint origin = { 21,21 };

NSRect rect;
rect.origin = origin;
rect.size.width = 128;
rect.size.height = 128;

NSBezierPath * path;
path = [NSBezierPath bezierPathWithRect:rect];

[path setLineWidth:4];

[[NSColor whiteColor] set];

[path fill];

[[NSColor grayColor] set];

[path stroke];

Complex Path Construction

The following examples incrementally build and draw several paths to construct the
final image. All of the code goes into the custom view's drawRect method.

First, we start by creating a basic oval in the center of the view.

// setup basic size and color properties

float dm = 81 * 2;
float rd = dm * 0.50;
float qt = dm * 0.25;

NSColor * white = [NSColor whiteColor];

NSColor * black = [NSColor blackColor];

NSBezierPath *path1, *path2, *path3, *path4;

// find the center of the view

float center = [self bounds].size.width * 0.50;
float middle = [self bounds].size.height * 0.50;

// create a rect in the center

NSPoint origin = { center - rd, middle - rd };
NSRect mainOval = { origin.x, origin.y, dm, dm };

// create a oval bezier path using the rect

path1 = [NSBezierPath bezierPathWithOvalInRect:mainOval];
[path1 setLineWidth:2.18];

// draw the path

[white set];[path1 fill];
[black set];[path1 stroke];

Next, we define a path to overlay on the first one. The path is built in three
parts, by appending three different arc paths to the original object.

Note how we build the ellipse in the top half by negating the clockwise option.

// overlay a new path to draw the right side

path2 = [NSBezierPath bezierPath];
// arc from the center to construct right side
NSPoint mainOvalCenter = { center, middle };
[path2 appendBezierPathWithArcWithCenter: mainOvalCenter
radius: rd
startAngle: 90
endAngle: 270
clockwise: YES];

// add a half-size arc at the top: counter clockwise

NSPoint curveOneCenter = { center, origin.y+qt };
[path2 appendBezierPathWithArcWithCenter: curveOneCenter
radius: qt
startAngle: 270
endAngle: 90
clockwise: NO];

// add a half-size arc in the bottom half

NSPoint curveTwoCenter = { center, origin.y+rd+qt };
[path2 appendBezierPathWithArcWithCenter: curveTwoCenter
radius: qt
startAngle: 270
endAngle: 90
clockwise: YES];

// fill the path on the right side with black

[black set];[path2 fill];

Finally, we build the paths for the two internal ellipses.

// calculate the size for each ellipses

float dotDm = ( qt * 0.618 );
float dotRd = ( dotDm * 0.5 );

// create a rect at the center of the top section

NSRect rect3 = NSMakeRect ( center - dotRd,
origin.y + (qt - dotRd),
dotDm,
dotDm );

// create an oval with the rect and fill it with black

path3 = [NSBezierPath bezierPathWithOvalInRect: rect3];
[black set];[path3 fill];

// copy the rect for the top ellipse and adjust the y axis
NSRect rect4 = rect3;
rect4.origin.y = NSMaxY(mainOval) - (qt + dotRd);

// create an oval with the rect and fill it with white

path4 = [NSBezierPath bezierPathWithOvalInRect: rect4];
[white set];[path4 fill];

The final result in our custom view.

Images
Cocoa's basic image class is NSImage. An image can draw itself into a view at
various sizes and levels of opacity, or can be written to disk.

Image objects can be created from files on disk, loaded from data in memory,
imported from the pasteboard, or drawn on the fly.

Each NSImage instance manages a series of NSImageRep objects which are versions of
the original image data suited to different contexts.

NSImage will automatically choose a representation when you draw into a view, but
you can also use an image rep directly. NSBitmapImageRep is perhaps the most
common.
Create and Display Images

Creating an NSImage from a file on disk and drawing it into a view is as simple as
calling initWithContentsOfFile followed by drawInRect. To make things look nice,
we'll center the image in the view and draw a border around it.

First, we need to use NSImageInterpolationHigh to to get smooth bitmap scaling,

then calculate the origin of the rect to draw the image in.

[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];

NSSize viewSize = [self bounds].size;

NSSize imageSize = { 250, 156 };

NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;

NSPoint imageOrigin = viewCenter;

imageOrigin.x -= imageSize.width * 0.50;
imageOrigin.y -= imageSize.height * 0.50;

NSRect destRect;
destRect.origin = imageOrigin;
destRect.size = imageSize;

We load the image from disk and flip it since our view uses a flipped coordinate
system. Once it's loaded, we draw it to the destination rect, than draw a border
around the same rect.

NSString * file = @"/Library/Desktop Pictures/Plants/Leaf Curl.jpg";

NSImage * image = [[NSImage alloc] initWithContentsOfFile:file];
[image setFlipped:YES];

[image drawInRect: destRect

fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];

NSBezierPath * path = [NSBezierPath bezierPathWithRect:destRect];

[path setLineWidth:3];
[[NSColor whiteColor] set];
[path stroke];

[image release];
Here's the final result drawn into the custom view.

In this example, the image is loaded from disk right before being drawn to the
view. This makes the code easier to follow, but it's very inefficient and makes
window resizing very slow.

A better approach is to load the image from disk once and store it in an instance
variable for drawing later. One of the following examples demonstrates that.
Overlay Images with Transparency

Cocoa can easily draw images as partially transparent, as seen in the following
example. First, we need to calculate the rects that we want to draw into,
centering the images in the view.

[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];

NSSize viewSize = [self bounds].size;

NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;

NSSize large = { 250, 156 };

NSSize small = { 125, 78 };

NSPoint origin = viewCenter;

origin.x -= (large.width+small.width) * 0.5;
origin.y -= large.height * 0.5;

// calculate the main image rect

NSRect largeRect;
largeRect.origin = origin;
largeRect.size = large;

// move to the right and resize

NSRect smallRect1 = largeRect;
smallRect1.origin.x += large.width;
smallRect1.size = small;

// move down
NSRect smallRect2 = smallRect1;
smallRect2.origin.y += small.height;

Next we need to load the images from disk and flip them to match our coordinate
system.

NSString * file1 = @"/Library/Desktop Pictures/Plants/Purple Frond.jpg";

NSString * file2 = @"/Library/Desktop Pictures/Plants/Agave.jpg";

NSImage * image1 = [[NSImage alloc] initWithContentsOfFile:file1];

NSImage * image2 = [[NSImage alloc] initWithContentsOfFile:file2];

[image1 setFlipped:YES];
[image2 setFlipped:YES];
Now each image draws itself into the view twice: once in the main large rect, and
once in a smaller rect. A single image object can draw itself any number of times.
The images are drawn on top of each other in the large rect, with 80% and 60%
opacity, respectively. After that, each image draws itself into a separate smaller
rect, fully opaque.

[image1 drawInRect: largeRect

fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 0.8];

[image2 drawInRect: largeRect

fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 0.6];

[image1 drawInRect: smallRect1

fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];

[image2 drawInRect: smallRect2

fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
Finally, we draw borders around the images.

[[NSColor whiteColor] set];

NSBezierPath *path = [NSBezierPath bezierPathWithRect: largeRect];

[path appendBezierPathWithRect: smallRect1];
[path appendBezierPathWithRect: smallRect2];
[path setLineWidth:2.5];
[path stroke];

[image1 release];
[image2 release];
Here's the final result.

Resizing the window is still slow in this example, because we're still loading the
image from disk frequently. The next example focuses on some optimization
techniques.
Draw Directly to an Image

Hint: This technique is also useful if your application needs to generate images
dynamically, or superimpose content on top of an existing image. The results can
be written to a file. We can optimize drawing multiple images to the screen by
combining them in into one image, then draw the composite version to the view.

This is called drawing into an "offscreen image" or "offscreen buffer", because

the pixels are collected for later use instead of being displayed on the screen
immediately.

To do this, we need to create an instance variable in the view named

compositeImage, and add a method to generate the image. The generated image will
be used in drawRect.
Below is the first part of the code for createCompositeImage. First, we set up an
array of image file names, and calculate the total size needed to hold all of
them.

- (void)createCompositeImage {

NSString * folder = @"/Library/Desktop Pictures/";

NSArray * files = [NSArray arrayWithObjects:
@"Plants/Petals.jpg",
@"Nature/Flowing Rock.jpg",
@"Plants/Maple.jpg", nil];

// make a size big enough to hold all images

int count = [files count];
NSRect rect = { 0,0, 150, 94};
NSSize compositeSize;
compositeSize.width = (rect.size.width * count);
compositeSize.height = rect.size.height;
Now we'll create the compositeImage object and draw into it using the lockFocus
method. Once lockFocus is called, all drawing goes directly into the image object
until unlockFocus is called.

Locking focus creates a new graphics context and also creates a new coordinate
system where (0,0) is the upper-left corner of the image, rather than the view
itself. For clarity, it's best to indent the code between locking and unlocking
focus.

The code below assumes standard accessors for compositeImage exist.

// -createCompositeImage continued...

NSImage * compositeImage;
compositeImage = [[NSImage alloc] initWithSize:compositeSize];

[compositeImage lockFocus];

// this image has its own graphics context, so

// we need to specify high interpolation again
[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];

int i;
NSImage * image;
NSString * file;

for ( i = 0; i < count; i++ )

{
// load the image from disk and draw it
// into the composite image

file = [folder stringByAppendingString:

[files objectAtIndex:i]];

image = [[NSImage alloc] initWithContentsOfFile:file];

[image setFlipped:YES];

[image drawInRect: rect

fromRect: NSZeroRect
 operation: NSCompositeSourceOver
fraction: 1.0];

[image release]; image = nil;

rect.origin.x += rect.size.width; // move right
}

[compositeImage unlockFocus];

[self setCompositeImage:compositeImage];
[compositeImage release];

} // end -createCompositeImage

Now we'll move on to drawing the composite image into the view.
Display the Composite Image

The composite image is drawn into the view in the NSView drawRect method, as shown
below.

- (void) drawRect: (NSRect)aRect {

NSImage * compositeImage = [self compositeImage];

if ( !compositeImage )
{
// if the image is nil, we need to create it
[self createCompositeImage];
compositeImage = [self compositeImage];
}

// find the center of the view

NSSize viewSize = [self bounds].size;
NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;

// calculate image rect to draw the image to

NSSize size = [compositeImage size];
NSRect rect;
rect.origin.x = viewCenter.x - (size.width * 0.50);
rect.origin.y = viewCenter.y - (size.height * 0.50);
rect.size = size;

// draw composite image

[compositeImage drawInRect: rect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];

// draw border
NSBezierPath * path = [NSBezierPath bezierPathWithRect:rect];
[path setLineWidth:2.5];
[[NSColor whiteColor] set];
[path stroke];

} // end of -drawRect

Here's our final result. You'll notice that resizing the window in this example is
much faster than in the previous examples because we're only loading the image
data once.

It's only necessary to draw into an offscreen image if you want to create a
combination of multiple images. Individual images can just be set as instance
variables and drawn as is.