iOS Developer Library

Developer

ApplicationServices Framework Reference CGGradient Reference

Options
Deployment Target:

On This Page
Language:

CGGradient Reference

A gradient defines a smooth transition between colors across an area. The CGGradientRef opaque type, and the functions that operate on it, make creating and using radial and axial gradient fills an easy task. A CGGradient object has a color space, two or more colors, and a location for each color. The color space cannot be a pattern or indexed color space, otherwise it can be any Quartz color space (CGColorSpaceRef).

Colors can be provided as component values (such as red, green, blue) or as Quartz color objects (CGColorRef). In Quartz, component can vary from 0.0 to 1.0, designating the proportion of the component present in the color.

A location is a normalized value. When it comes time to paint the gradient, Quartz maps the normalized location values to the points in coordinate space that you provide.

If you want more precise control over gradients, or if your application runs in versions of OS X that are earlier than v10.5, see CGShading Reference.

Functions

  • Creates a CGGradient object from a color space and the provided color components and locations.

    Declaration

    Swift

    func CGGradientCreateWithColorComponents(_ space: CGColorSpace!, _ components: UnsafePointer<CGFloat>, _ locations: UnsafePointer<CGFloat>, _ count: UInt) -> CGGradient!

    Objective-C

    CGGradientRef CGGradientCreateWithColorComponents ( CGColorSpaceRef space, const CGFloat components[], const CGFloat locations[], size_t count );

    Parameters

    space

    The color space to use for the gradient. You cannot use a pattern or indexed color space.

    components

    The color components for each color that defines the gradient. The components should be in the color space specified by space. If you are unsure of the number of components, you can call the function CGColorSpaceGetNumberOfComponents.

    The number of items in this array should be the product of count and the number of components in the color space. For example, if the color space is an RGBA color space and you want to use two colors in the gradient (one for a starting location and another for an ending location), then you need to provide 8 values in components—red, green, blue, and alpha values for the first color, followed by red, green, blue, and alpha values for the second color.

    locations

    The location for each color provided in components. Each location must be a CGFloat value in the range of 0 to 1, inclusive. If 0 and 1 are not in the locations array, Quartz uses the colors provided that are closest to 0 and 1 for those locations.

    If locations is NULL, the first color in colors is assigned to location 0, the last color incolors is assigned to location 1, and intervening colors are assigned locations that are at equal intervals in between.

    count

    The number of locations provided in the locations parameters.

    Return Value

    A CGGradient object.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a CGGradient object from a color space and the provided color objects and locations.

    Declaration

    Swift

    func CGGradientCreateWithColors(_ space: CGColorSpace!, _ colors: CFArray!, _ locations: UnsafePointer<CGFloat>) -> CGGradient!

    Objective-C

    CGGradientRef CGGradientCreateWithColors ( CGColorSpaceRef space, CFArrayRef colors, const CGFloat locations[] );

    Parameters

    space

    The color space to use for the gradient. You cannot use a pattern or indexed color space.

    colors

    A non-empty array of CGColor objects that should be in the color space specified by space. If space is not NULL, each color will be converted (if necessary) to that color space and the gradient will drawn in that color space. Otherwise, each color will be converted to and drawn in the GenericRGB color space.

    locations

    The location for each color provided in colors; each location must be a CGFloat value in the range of 0 to 1, inclusive. If 0 and 1 are not in the locations array, Quartz uses the colors provided that are closest to 0 and 1 for those locations.

    If locations is NULL, the first color in colors is assigned to location 0, the last color incolors is assigned to location 1, and intervening colors are assigned locations that are at equal intervals in between.

    The locations array should contain the same number of items as the colors array.

    Return Value

    A CGGradient object.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Decrements the retain count of a CGGradient object.

    Declaration

    Objective-C

    void CGGradientRelease ( CGGradientRef gradient );

    Parameters

    gradient

    The gradient object to release.

    Discussion

    This function is equivalent to CFRelease, except that it does not cause an error if the gradient parameter is NULL.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in iOS 2.0 and later.

  • Increments the retain count of a CGGradient object.

    Declaration

    Objective-C

    CGGradientRef CGGradientRetain ( CGGradientRef gradient );

    Parameters

    gradient

    The gradient object to retain.

    Return Value

    The same gradient object that you passed in as the gradient parameter.

    Discussion

    This function is equivalent to CFRetain, except that it does not cause an error if the gradient parameter is NULL.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in iOS 2.0 and later.

  • Returns the Core Foundation type identifier for CGGradient objects.

    Declaration

    Swift

    func CGGradientGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGGradientGetTypeID ( void );

    Return Value

    The Core Foundation identifier for the opaque type CGGradientRef.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Data Types

  • An opaque type that represents a Quartz gradient.

    Declaration

    Swift

    typealias CGGradientRef = CGGradient

    Objective-C

    typedef struct CGGradient *CGGradientRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Constants

  • Drawing locations for gradients.

    Declaration

    Swift

    typealias CGGradientDrawingOptions = UInt32

    Objective-C

    enum { kCGGradientDrawsBeforeStartLocation = (1 << 0), kCGGradientDrawsAfterEndLocation = (1 << 1) }; typedef enum CGGradientDrawingOptions CGGradientDrawingOptions;

    Constants

    • kCGGradientDrawsBeforeStartLocation

      kCGGradientDrawsBeforeStartLocation

      The fill should extend beyond the starting location. The color that extends beyond the starting point is the solid color defined by the CGGradient object to be at location 0.

      Available in iOS 2.0 and later.

    • kCGGradientDrawsAfterEndLocation

      kCGGradientDrawsAfterEndLocation

      The fill should extend beyond the ending location. The color that extends beyond the ending point is the solid color defined by the CGGradient object to be at location 1.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.