Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Using a CGGradient Object

The CGGradient object is an abstract definition of a gradient—it simply specifies colors and locations, but not the geometry. You can use this same object for both axial and radial geometries. As an abstract definition, CGGradient objects are perhaps more readily reusable than their counterparts, CGShading objects. Not having the geometry locked in the CGGradient object allows for the possibility of iteratively painting gradients based on the same color scheme without the need for also tying up memory resources in multiple CGGradient objects.

Because Quartz calculates the gradient for you, using a CGGradient object to create and draw a gradient is fairly straightforward, requiring these steps:

1. Create a CGGradient object, supplying a colorspace, an array of two or more color components, an array or two or more locations , and the number of items in each of the two arrays.

2. Paint the gradient by calling either CGContextDrawLinearGradient or CGContextDrawRadialGradient and supplying a context, a CGGradient object, drawing options, and the stating and ending geometry (points for axial gradients or circle centers and radii for radial gradients).

3. Release the CGGradient object when you no longer need it.

A location is a CGFloat value in the range of 0.0 to 1.0, inclusive that specifies the normalized distance along axis of the gradient. A value of 0.0 specifies the starting point of the axis, while 1.0 specifies the ending point of the axis. Other values specify a proportion of the distance, such as 0.25 for one-fourth of the distance from the starting point and 0.5 for the halfway point on the axis. At a minimum, Quartz uses two locations. If you pass NULL for the locations array, Quartz uses 0 for the first location and 1 for the second.

The number of color components per color depends on the colorspace. For onscreen drawing, you’ll use an RGB colorspace. Because Quartz draws with alpha, each onscreen color has four components—red, green, blue, and alpha. So, for onscreen drawing, the number of elements in the color component array that you provide must contain four times the number of locations. Quartz RGBA color components can vary in value from 0.0 to 1.0, inclusive.

Listing 8-1 is a code fragment that creates a CGGradient object. After declaring the necessary variables, the code sets the locations and the requisite number of color components (for this example, 2 X 4 = 8). It creates a generic RGB colorspace. Then, it passes the necessary parameters to the function CGGradientCreateWithColorComponents. You can also use the function CGGradientCreateWithColors which is convenient if your application sets up CGColor objects.

Listing 8-1  A code fragment that creates a CGGradient object

CGGradientRef myGradient;

CGColorSpaceRef myColorspace;

size_t num_locations = 2;

CGFloat locations[2] = { 0.0., 1.0 };

CGFloat components[8] = { 1.0, 0.5, 0.4, 1.0,  // Start color

                          0.8, 0.8, 0.3, 1.0 }; // End color

myColorspace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);

myGradient = CGGradientCreateWithColorComponents (myColorspace, components,

                          locations, num_locations);

After you create a CGGradient object, you can use it to paint an axial or linear gradient. Listing 8-2 is a code fragment that declares and sets the starting and ending points for a linear gradient and then paints the gradient. Figure 8-1 shows the result. The code does not show how to obtain the CGContext object (myContext).

Listing 8-2  A code fragment that paints an axial gradient using a CGGradient object

CGPoint myStartPoint, myEndPoint;

myStartPoint.x = 0.0;

myStartPoint.y = 0.0;

myEndPoint.x = 1.0;

myEndPoint.y = 1.0;

CGContextDrawLinearGradient (myContext, myGradient, myStartPoint, myEndPoint, 0);

Listing 8-3 is a code fragment that uses the CGGradient object created in Listing 8-1 to paint the radial gradient shown in Figure 8-9. This example illustrates the result of extending the area of the gradient by filling it with a solid color.

Listing 8-3  A code fragment that paints a radial gradient using a CGGradient object

CGPoint myStartPoint, myEndPoint;

CGFloat myStartRadius, myEndRadius;

myStartPoint.x = 0.15;

myStartPoint.y = 0.15;

myEndPoint.x = 0.5;

myEndPoint.y = 0.5;

myStartRadius = 0.1;

myEndRadius = 0.25;

CGContextDrawRadialGradient (myContext, myGradient, myStartPoint,

                         myStartRadius, myEndPoint, myEndRadius,

                         kCGGradientDrawsAfterEndLocation);

Figure 8-9  A radial gradient painted using a CGGradient object

The radial gradient shown in Figure 8-4 was created using the variables shown in Listing 8-4.

Listing 8-4  The variables used to create a radial gradient by varying alpha

CGPoint myStartPoint, myEndPoint;

CGFloat myStartRadius, myEndRadius;

myStartPoint.x = 0.2;

myStartPoint.y = 0.5;

myEndPoint.x = 0.65;

myEndPoint.y = 0.5;

myStartRadius = 0.1;

myEndRadius = 0.25;

size_t num_locations = 2;

CGFloat locations[2] = { 0, 1.0 };

CGFloat components[8] = { 0.95, 0.3, 0.4, 1.0,

                          0.95, 0.3, 0.4, 0.1 };

Listing 8-5 shows the variables used to create the gray gradient shown in Figure 8-10, which has three locations.

Listing 8-5  The variables used to create a gray gradient

size_t num_locations = 3;

CGFloat locations[3] = { 0.0, 0.5, 1.0};

CGFloat components[12] = {  1.0, 1.0, 1.0, 1.0,

                            0.5, 0.5, 0.5, 1.0,

                            1.0, 1.0, 1.0, 1.0 };

Figure 8-10  An axial gradient with three locations

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice