Mac Developer Library

Developer

AppKit Framework Reference NSGradient Class Reference

Options
Deployment Target:

On This Page
Language:

NSGradient

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.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.
  • Initializes a newly allocated gradient object with two colors.

    Declaration

    Swift

    convenience init(startingColor startingColor: NSColor, endingColor endingColor: NSColor)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    convenience init!(colors colorArray: [AnyObject])

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    init(colors colorArray: [AnyObject], atLocations locations: UnsafePointer<CGFloat>, colorSpace colorSpace: NSColorSpace)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func drawFromPoint(_ startingPoint: NSPoint, toPoint endingPoint: NSPoint, options options: NSGradientDrawingOptions)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Draws a radial gradient between the specified circles.

    Declaration

    Swift

    func drawFromCenter(_ startCenter: NSPoint, radius startRadius: CGFloat, toCenter endCenter: NSPoint, radius endRadius: CGFloat, options options: NSGradientDrawingOptions)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Fills the specified rectangle with a linear gradient.

    Declaration

    Swift

    func drawInRect(_ rect: NSRect, angle angle: CGFloat)

    Objective-C

    - (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.

    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.

    The gradient drawn by this method is clipped to rect.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Fills the specified path with a linear gradient.

    Declaration

    Swift

    func drawInBezierPath(_ path: NSBezierPath, angle angle: CGFloat)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func drawInRect(_ rect: NSRect, relativeCenterPosition relativeCenterPosition: NSPoint)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func drawInBezierPath(_ path: NSBezierPath, relativeCenterPosition relativeCenterPosition: NSPoint)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The color space of the colors associated with the gradient. (read-only)

    Declaration

    Swift

    var colorSpace: NSColorSpace { get }

    Objective-C

    @property(readonly, strong) NSColorSpace *colorSpace

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The number of color stops associated with the gradient. (read-only)

    Declaration

    Swift

    var numberOfColorStops: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfColorStops

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func getColor(_ color: AutoreleasingUnsafeMutablePointer<NSColor?>, location location: UnsafeMutablePointer<CGFloat>, atIndex index: Int)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func interpolatedColorAtLocation(_ location: CGFloat) -> NSColor

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

Data Types

  • Specifies gradient drawing options.

    Declaration

    Swift

    typealias NSGradientDrawingOptions = Int

    Objective-C

    typedef NSUInteger NSGradientDrawingOptions;

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var NSGradientDrawsBeforeStartingLocation: Int { get } var NSGradientDrawsAfterEndingLocation: Int { get }

    Objective-C

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

    Constants

    • NSGradientDrawsBeforeStartingLocation

      NSGradientDrawsBeforeStartingLocation

      Drawing extends before the gradient starting point.

      Available in OS X v10.5 and later.

    • NSGradientDrawsAfterEndingLocation

      NSGradientDrawsAfterEndingLocation

      Drawing extends beyond the gradient end point.

      Available in OS X v10.5 and later.