---

NSGradient Class Reference

Overview

The NSGradient class provides support for drawing gradient fill colors, also known as shadings in Quartz. This class provides convenience methods for drawing radial or linear (axial) gradients for rectangles and NSBezierPath objects. It also supports primitive methods that let you customize the shape of the gradient fill.

A gradient consists of two or more color changes over the range of the gradient shape. When creating a gradient object, you specify the colors and their locations relative to the start and end of the gradient. This combination of color and location is known as a color stop. During drawing, the NSGradient object uses the color stop information to compute color changes for you and passes that information to the Quartz shading functions.

Because the NSGradient class uses Quartz shadings, drawing is handled by computing the colors at a given point mathematically. This technique results in smooth gradients regardless of the resolution of the target device.

For more information about gradients and their appearance, see Gradients in Quartz 2D Programming Guide.

Tasks

Initialization

• – initWithStartingColor:endingColor:
• – initWithColors:
• – initWithColorsAndLocations:
• – initWithColors:atLocations:colorSpace:

Primitive Drawing Methods

• – drawFromPoint:toPoint:options:
• – drawFromCenter:radius:toCenter:radius:options:

Drawing Linear Gradients

• – drawInRect:angle:
• – drawInBezierPath:angle:

Drawing Radial Gradients

• – drawInRect:relativeCenterPosition:
• – drawInBezierPath:relativeCenterPosition:

Getting Gradient Properties

• – colorSpace
• – numberOfColorStops
• – getColor:location:atIndex:
• – interpolatedColorAtLocation:

Instance Methods

colorSpace

Returns the color space of the colors associated with the receiver.

- (NSColorSpace *)colorSpace

Return Value

The color space object used by the receiver’s colors.

Discussion

When the receiver is initialized, colors that do not conform to the receiver’s color space are converted automatically.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

drawFromCenter:radius:toCenter:radius:options:

Draws a radial gradient between the specified circles.

- (void)drawFromCenter:(NSPoint)startCenter radius:(CGFloat)startRadius toCenter:(NSPoint)endCenter radius:(CGFloat)endRadius options:(NSGradientDrawingOptions)options

Parameters

startCenter

The center point of the circle that represents the beginning of the gradient.

startRadius

The radius of the circle that represents the beginning of the gradient.

endCenter

The center point of the circle that represents the end of the gradient.

endRadius

The radius of the circle that represents the end of the gradient.

options

The gradient options, if any. You can use these options to extend the gradient size beyond the start and end circles. For more information, see “Gradient Drawing Options”.

Discussion

This method draws a radial gradient pattern starting at the first circle and ending at the second circle. The gradient color transitions occur in circular bands emanating from the starting circle and ending at the second circle.

This is a primitive method used by the NSGradient class to draw radial gradients. Because this method does not perform any clipping of the gradient fill pattern, you must ensure that the clipping region is configured properly if you intend to invoke this method directly. By default, the clipping region is set to the current view or window in which drawing occurs.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

drawFromPoint:toPoint:options:

Draws a linear gradient between the specified start and end points.

- (void)drawFromPoint:(NSPoint)startingPoint toPoint:(NSPoint)endingPoint options:(NSGradientDrawingOptions)options

Parameters

startingPoint

The starting point for the gradient, in the local coordinate system. The gradient’s first color is drawn at this point.

endingPoint

The end point for the gradient, in the local coordinate system. The gradient’s last color is drawn at this point.

options

The gradient options, if any. You can use these options to extend the gradient size beyond the start and end points. For more information, see “Gradient Drawing Options”.

Discussion

This method draws the gradient color changes along the line formed by the two points. The gradient fill extends perpendicularly outward from line until it reaches the edges of the current clipping region.

This is a primitive method used by the NSGradient class to draw linear gradients. Because this method does not perform any clipping of the gradient fill pattern, you must ensure that the clipping region is configured properly if you intend to invoke this method directly. By default, the clipping region is set to the current view or window in which drawing occurs.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

drawInBezierPath:angle:

Fills the specified path with a linear gradient.

- (void)drawInBezierPath:(NSBezierPath *)path angle:(CGFloat)angle

Parameters

path

The path object to fill.

angle

The angle of the linear gradient, specified in degrees. Positive values indicate rotation in the counter-clockwise direction relative to the horizontal axis.

Discussion

This convenience method behaves in a similar way to the drawInRect:angle: method, with the path object replacing the rectangle as the clipping region. Like the other method, the start and end colors are guaranteed to be visible at the farthest ends of the path.

The gradient formed by this method is clipped to path.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – drawInRect:angle:
• – drawFromPoint:toPoint:options:

Declared In

NSGradient.h

drawInBezierPath:relativeCenterPosition:

Draws a radial gradient starting at the center point of the specified path.

- (void)drawInBezierPath:(NSBezierPath *)path relativeCenterPosition:(NSPoint)relativeCenterPosition

Parameters

path

The path to fill.

relativeCenterPosition

The relative location within the bounding rectangle of path to use as the center point of the gradient’s end circle. Each coordinate must contain a value between -1.0 and 1.0. A coordinate value of 0 represents the center of the path’s bounding rectangle along the given axis. In the default coordinate system, a value of -1.0 corresponds to the bottom or left edge of the bounding rectangle and a value of 1.0 corresponds to the top or right edge.

Discussion

The center point of the starting circle is the same as the center point of path. The radius of the starting circle is 0, resulting in the starting circle being just a point.

The center point of the end circle starts at the center point of path and is modified by the value in the relativeCenterPosition parameter. For example, if relativeCenterPosition contains the point (1.0, 1.0), the center of the end circle is located in the top-right corner of the path’s bounding rectangle. The radius of the end circle is set to the smallest value that ensures rect is covered by the end circle.

The gradient formed by this method is clipped to path.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – drawInRect:relativeCenterPosition:
• – drawFromCenter:radius:toCenter:radius:options:

Declared In

NSGradient.h

drawInRect:angle:

Fills the specified rectangle with a linear gradient.

- (void)drawInRect:(NSRect)rect angle:(CGFloat)angle

Parameters

rect

The rectangle to fill.

angle

The angle of the linear gradient, specified in degrees. Positive values indicate rotation in the counter-clockwise direction relative to the horizontal axis.

Discussion

This convenience method draws a linear gradient inside the specified rectangle. The gradient is drawn so that the start and end colors are guaranteed to be visible in opposite corners of the rectangle. The angle of rotation determines which corner contains the start color; see Table 1.

The gradient’s color transitions occur along the line formed by the angle of rotation. For example, a rotation of 0 degrees results in colors changing from left-to-right across the rectangle, while a rotation of 90 degrees results in colors changing from bottom to top.

The gradient drawn by this method is clipped to rect.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – drawInBezierPath:angle:
• – drawFromPoint:toPoint:options:

Declared In

NSGradient.h

drawInRect:relativeCenterPosition:

Draws a radial gradient starting at the center of the specified rectangle.

- (void)drawInRect:(NSRect)rect relativeCenterPosition:(NSPoint)relativeCenterPosition

Parameters

rect

The rectangle to fill.

relativeCenterPosition

The relative location within the rectangle to use as the center point of the gradient’s end circle. Each coordinate must contain a value between -1.0 and 1.0. A coordinate value of 0 represents the center of rect along the given axis. In the default coordinate system, a value of -1.0 corresponds to the bottom or left edge of the rectangle and a value of 1.0 corresponds to the top or right edge.

Discussion

The center point of the starting circle is the same as the center point of rect. The radius of the starting circle is 0, resulting in the starting circle being just a point.

The center point of the end circle starts at the center point of rect and is modified by the value in the relativeCenterPosition parameter. For example, if relativeCenterPosition contains the point (1.0, 1.0), the center of the end circle is located in the top-right corner of rect. The radius of the end circle is set to the smallest value that ensures rect is covered by the end circle.

The gradient formed by this method is clipped to rect.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – drawInRect:relativeCenterPosition:
• – drawFromCenter:radius:toCenter:radius:options:

Declared In

NSGradient.h

getColor:location:atIndex:

Returns information about the color stop at the specified index in the receiver’s color array.

- (void)getColor:(NSColor **)color location:(CGFloat *)location atIndex:(NSInteger)index

Parameters

color

On input, a pointer to a color object. On output, the color at the specified index in the receiver’s color array. You may specify nil if you are not interested in this parameter.

location

On input, a pointer to a floating point number. On output, contains the location value associated with the color. This value is between 0.0 and 1.0. It is used to determine the position of the color relative to the start and end points of the gradient. You may specify NULL if you are not interested in this parameter.

index

The index of the color you want.

Discussion

This method returns the color stop information that was used to create the receiver. It does not return the interpolated color values at any point along the gradient. The location of the gradient’s first color is typically 0.0 and the location of the last color is typically 1.0, although the locations can vary depending on how the receiver was created.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – numberOfColorStops
• – interpolatedColorAtLocation:

Declared In

NSGradient.h

initWithColors:

Initializes a newly allocated gradient object with an array of colors.

- (id)initWithColors:(NSArray *)colorArray

Parameters

colorArray

An array of NSColor objects representing the colors to use to initialize the gradient. There must be at least two colors in the array. The first color is placed at location 0.0 and the last at location 1.0. If there are more than two colors, the additional colors are placed at evenly spaced intervals between the first and last colors.

Return Value

The initialized NSGradient object.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – initWithColors:atLocations:colorSpace:

Declared In

NSGradient.h

initWithColors:atLocations:colorSpace:

Initializes a newly allocated gradient object with the specified colors, color locations, and color space.

- (id)initWithColors:(NSArray *)colorArray atLocations:(const CGFloat *)locations colorSpace:(NSColorSpace *)colorSpace

Parameters

colorArray

An array of NSColor objects representing the colors in the gradient.

locations

An array of CGFloat values containing the location for each color in the gradient. Each value must be in the range 0.0 to 1.0. There must be the same number of locations as are colors in the colorArray parameter.

colorSpace

The color space to use for the gradient.

Return Value

The initialized NSGradient object.

Discussion

This method is the designated initializer of NSGradient. The colors in the colorArray parameter are converted to the specified color space if they are not already in that color space.

Typically, at least one color should have a location of 0.0 and one should have a location of 1.0. If these locations are not specified, the color at the closest color stop is used to fill the gap.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

initWithColorsAndLocations:

Initializes a newly allocated gradient object with a comma-separated list of arguments.

- (id)initWithColorsAndLocations:(NSColor *)firstColor, ...

Parameters

firstColor

The first color in the gradient.

...

A comma-separated list of alternating NSColor objects and location arguments (specified as CGFloat values). The first value after firstColor must be a location. Each location value must be between 0.0 and 1.0. The list must be nil-terminated.

Return Value

The initialized NSGradient object.

Discussion

Typically, at least one color should have a location of 0.0 and one should have a location of 1.0. If these locations are not specified, the color at the closest color stop is used to fill the gap.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – initWithColors:atLocations:colorSpace:

Declared In

NSGradient.h

initWithStartingColor:endingColor:

Initializes a newly allocated gradient object with two colors.

- (id)initWithStartingColor:(NSColor *)startingColor endingColor:(NSColor *)endingColor

Parameters

startingColor

The starting color of the gradient. The location of this color is fixed at 0.0.

endingColor

The ending color of the gradient. The location of this color is fixed at 1.0.

Return Value

The initialized NSGradient object.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – initWithColors:atLocations:colorSpace:

Related Sample Code

• Grady
• MenuItemView

Declared In

NSGradient.h

interpolatedColorAtLocation:

Returns the color of the rendered gradient at the specified relative location.

- (NSColor *)interpolatedColorAtLocation:(CGFloat)location

Parameters

location

The location value for the color you want. This value must be between 0.0 and 1.0. This value need not correspond to the location of one of the color objects used to create the gradient.

Discussion

This method does not simply return the color values used to initialize the receiver. Instead, it computes the value that would be drawn at the specified location.

The start color of the gradient is always located at 0.0 and the end color is always at 1.0.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

numberOfColorStops

Returns the number of color stops associated with the receiver.

- (NSInteger)numberOfColorStops

Return Value

The number of colors in the receiver’s color array.

Discussion

Gradients must have at least two color stops: one defining the location of the start color and one defining the location of the end color. Gradients may have additional color stops located at different transition points in between the start and end stops.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

Constants

NSGradientDrawingOptions

Specifies gradient drawing options.

typedef NSUInteger NSGradientDrawingOptions;

Discussion

The constant values associated with this type are listed in “Gradient Drawing Options.”

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSGradient.h

Gradient Drawing Options

These constants are used by the primitive drawing methods to determine if drawing occurs outside of the gradient start and end locations.

enum {
   NSGradientDrawsBeforeStartingLocation =   (1 << 0),
   NSGradientDrawsAfterEndingLocation =    (1 << 1),
};

Constants

NSGradientDrawsBeforeStartingLocation

Drawing extends before the gradient starting point.

Available in Mac OS X v10.5 and later.

Declared in NSGradient.h.

NSGradientDrawsAfterEndingLocation

Drawing extends beyond the gradient end point.

Available in Mac OS X v10.5 and later.

Declared in NSGradient.h.

Declared In

AppKit/NSGradient.h

---