NSGradient Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.5 and later. |
| Companion guide | |
| Declared in | NSGradient.h |
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
Drawing Linear Gradients
Drawing Radial Gradients
Getting Gradient Properties
Instance Methods
colorSpace
Returns the color space of the colors associated with the receiver.
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 OS X v10.5 and later.
Declared In
NSGradient.hdrawFromCenter:radius:toCenter:radius:options:
Draws a radial gradient between the specified circles.
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 OS X v10.5 and later.
Declared In
NSGradient.hdrawFromPoint:toPoint:options:
Draws a linear gradient between the specified start and end points.
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 OS X v10.5 and later.
Declared In
NSGradient.hdrawInBezierPath:angle:
Fills the specified path with a linear gradient.
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 OS X v10.5 and later.
Declared In
NSGradient.hdrawInBezierPath:relativeCenterPosition:
Draws a radial gradient starting at the center point of the specified path.
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 OS X v10.5 and later.
Declared In
NSGradient.hdrawInRect:angle:
Fills the specified rectangle with a linear gradient.
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.
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.
The gradient drawn by this method is clipped to rect.
Availability
- Available in OS X v10.5 and later.
Declared In
NSGradient.hdrawInRect:relativeCenterPosition:
Draws a radial gradient starting at the center of the specified rectangle.
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 OS X v10.5 and later.
Declared In
NSGradient.hgetColor:location:atIndex:
Returns information about the color stop at the specified index in the receiver’s color array.
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
nilif 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
NULLif 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 OS X v10.5 and later.
Declared In
NSGradient.hinitWithColors:
Initializes a newly allocated gradient object with an array of colors.
Parameters
- colorArray
An array of
NSColorobjects 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 OS X v10.5 and later.
Declared In
NSGradient.hinitWithColors:atLocations:colorSpace:
Initializes a newly allocated gradient object with the specified colors, color locations, and color space.
Parameters
- colorArray
An array of
NSColorobjects representing the colors in the gradient.- locations
An array of
CGFloatvalues 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 OS X v10.5 and later.
Declared In
NSGradient.hinitWithColorsAndLocations:
Initializes a newly allocated gradient object with a comma-separated list of arguments.
Parameters
- firstColor
The first color in the gradient.
- ...
A comma-separated list of alternating
NSColorobjects and location arguments (specified asCGFloatvalues). The first value afterfirstColormust be a location. Each location value must be between 0.0 and 1.0. The list must benil-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 OS X v10.5 and later.
Declared In
NSGradient.hinitWithStartingColor:endingColor:
Initializes a newly allocated gradient object with two colors.
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 OS X v10.5 and later.
Declared In
NSGradient.hinterpolatedColorAtLocation:
Returns the color of the rendered gradient at the specified relative 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 OS X v10.5 and later.
Declared In
NSGradient.hnumberOfColorStops
Returns the number of color stops associated with the receiver.
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 OS X v10.5 and later.
Declared In
NSGradient.hConstants
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 OS X v10.5 and later.
Declared In
NSGradient.hGradient 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
NSGradientDrawsBeforeStartingLocationDrawing extends before the gradient starting point.
Available in OS X v10.5 and later.
Declared in
NSGradient.h.NSGradientDrawsAfterEndingLocationDrawing extends beyond the gradient end point.
Available in OS X v10.5 and later.
Declared in
NSGradient.h.
Declared In
AppKit/NSGradient.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)