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.

Declaration

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.

Declaration

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.

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.

Parameters

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.

Parameters

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.

Declaration

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.

Table 1Linear gradient starting points.

Rotation angle

Start corner

0-89 degrees

Lower-left

90-179 degrees

Lower-right

180-269 degrees

Upper-right

270-359 degrees

Upper-left

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.

Declaration

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.

Declaration

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.

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.

Declaration

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.

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.