Mac Developer Library

Developer

ApplicationServices Framework Reference CGColor Reference

Options
Deployment Target:

On This Page
Language:

CGColor Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreGraphics

Objective-C

@import CoreGraphics;

The CGColorRef opaque type contains a set of components (such as red, green, and blue) that uniquely define a color, and a color space that specifies how those components should be interpreted. Quartz color objects provide a fast and convenient way to manage and set colors, especially colors that are used repeatedly. Quartz drawing operations use color objects for setting fill and stroke colors, managing alpha, and setting color with a pattern.

See also these related references: CGContext Reference, CGColorSpace Reference, and CGPattern Reference.

Functions

  • Returns a color object that represents a constant color.

    Declaration

    Swift

    func CGColorGetConstantColor(_ colorName: CFString!) -> CGColor!

    Objective-C

    CGColorRef CGColorGetConstantColor ( CFStringRef colorName );

    Parameters

    colorName

    A color name. You can pass any of the “Constant Colors” constant.

    Return Value

    A color object.

    Discussion

    As CGColorGetConstantColor is not a “Copy” or “Create” function, it does not necessarily return a new reference each time it's called. As a consequence, you should not release the returned value. However, colors returned from CGColorGetConstantColor can be retained and released in a properly nested fashion, just as any other Core Foundation type can.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Decrements the retain count of a Quartz color.

    Declaration

    Objective-C

    void CGColorRelease ( CGColorRef color );

    Parameters

    color

    The Quartz color to release.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.3 and later.

  • Increments the retain count of a Quartz color.

    Declaration

    Objective-C

    CGColorRef CGColorRetain ( CGColorRef color );

    Parameters

    color

    The Quartz color to retain.

    Return Value

    The same color you passed in as the color parameter.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.3 and later.

  • Creates a Quartz color using a list of intensity values (including alpha) and an associated color space.

    Declaration

    Swift

    func CGColorCreate(_ colorspace: CGColorSpace!, _ components: UnsafePointer<CGFloat>) -> CGColor!

    Objective-C

    CGColorRef CGColorCreate ( CGColorSpaceRef space, const CGFloat components[] );

    Parameters

    colorspace

    A color space for the new color. Quartz retains this object; upon return, you may safely release it.

    components

    An array of intensity values describing the color. The array should contain n+1 values that correspond to the n color components in the specified color space, followed by the alpha component. Each component value should be in the range appropriate for the color space. Values outside this range will be clamped to the nearest correct value.

    Return Value

    A new Quartz color. You are responsible for releasing this object using CGColorRelease.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Creates a copy of an existing Quartz color.

    Declaration

    Swift

    func CGColorCreateCopy(_ color: CGColor!) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateCopy ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    A copy of the specified color. You are responsible for releasing this object using CGColorRelease.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Creates a color in the Generic gray color space.

    Declaration

    Swift

    func CGColorCreateGenericGray(_ gray: CGFloat, _ alpha: CGFloat) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateGenericGray ( CGFloat gray, CGFloat alpha );

    Parameters

    gray

    A grayscale value (0.0 - 1.0).

    alpha

    An alpha value (0.0 - 1.0).

    Return Value

    A color object.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Creates a color in the Generic RGB color space.

    Declaration

    Swift

    func CGColorCreateGenericRGB(_ red: CGFloat, _ green: CGFloat, _ blue: CGFloat, _ alpha: CGFloat) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateGenericRGB ( CGFloat red, CGFloat green, CGFloat blue, CGFloat alpha );

    Parameters

    red

    A red component value (0.0 - 1.0).

    green

    A green component value (0.0 - 1.0).

    blue

    A blue component value (0.0 - 1.0).

    alpha

    An alpha value (0.0 - 1.0).

    Return Value

    A color object.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Creates a color in the Generic CMYK color space.

    Declaration

    Swift

    func CGColorCreateGenericCMYK(_ cyan: CGFloat, _ magenta: CGFloat, _ yellow: CGFloat, _ black: CGFloat, _ alpha: CGFloat) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateGenericCMYK ( CGFloat cyan, CGFloat magenta, CGFloat yellow, CGFloat black, CGFloat alpha );

    Parameters

    cyan

    A cyan value (0.0 - 1.0).

    magenta

    A magenta value (0.0 - 1.0).

    yellow

    A yellow value (0.0 - 1.0).

    black

    A black value (0.0 - 1.0).

    alpha

    An alpha value (0.0 - 1.0).

    Return Value

    A color object.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Creates a copy of an existing Quartz color, substituting a new alpha value.

    Declaration

    Swift

    func CGColorCreateCopyWithAlpha(_ color: CGColor!, _ alpha: CGFloat) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateCopyWithAlpha ( CGColorRef color, CGFloat alpha );

    Parameters

    color

    The Quartz color to copy.

    alpha

    A value that specifies the desired opacity of the copy. Values outside the range [0,1] are clamped to 0 or 1.

    Return Value

    A copy of the specified color, using the specified alpha value. You are responsible for releasing this object using CGColorRelease.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Creates a Quartz color using a list of intensity values (including alpha), a pattern color space, and a pattern.

    Declaration

    Swift

    func CGColorCreateWithPattern(_ colorspace: CGColorSpace!, _ pattern: CGPattern!, _ components: UnsafePointer<CGFloat>) -> CGColor!

    Objective-C

    CGColorRef CGColorCreateWithPattern ( CGColorSpaceRef space, CGPatternRef pattern, const CGFloat components[] );

    Parameters

    colorspace

    A pattern color space for the new color. Quartz retains the color space you pass in. On return, you may safely release it.

    pattern

    A pattern for the new color object. Quartz retains the pattern you pass in. On return, you may safely release it.

    components

    An array of intensity values describing the color. The array should contain n + 1 values that correspond to the n color components in the specified color space, followed by the alpha component. Each component value should be in the range appropriate for the color space. Values outside this range will be clamped to the nearest correct value.

    Return Value

    A new Quartz color. You are responsible for releasing this object using CGColorRelease.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Indicates whether two colors are equal.

    Declaration

    Swift

    func CGColorEqualToColor(_ color1: CGColor!, _ color2: CGColor!) -> Bool

    Objective-C

    bool CGColorEqualToColor ( CGColorRef color1, CGColorRef color2 );

    Parameters

    color1

    The first Quartz color to compare.

    color2

    The second Quartz color to compare.

    Return Value

    A Boolean value that, if true, indicates that the specified colors are equal. If the colors are not equal, the value is false.

    Discussion

    Two colors are equal if they have equal color spaces and numerically equal color components.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the value of the alpha component associated with a Quartz color.

    Declaration

    Swift

    func CGColorGetAlpha(_ color: CGColor!) -> CGFloat

    Objective-C

    CGFloat CGColorGetAlpha ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    An alpha intensity value in the range [0,1]. The value represents the opacity of the color.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the color space associated with a Quartz color.

    Declaration

    Swift

    func CGColorGetColorSpace(_ color: CGColor!) -> CGColorSpace!

    Objective-C

    CGColorSpaceRef CGColorGetColorSpace ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    The Quartz color space for the specified color. You are responsible for retaining and releasing it as needed.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the values of the color components (including alpha) associated with a Quartz color.

    Declaration

    Swift

    func CGColorGetComponents(_ color: CGColor!) -> UnsafePointer<CGFloat>

    Objective-C

    const CGFloat * CGColorGetComponents ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    An array of intensity values for the color components (including alpha) associated with the specified color. The size of the array is one more than the number of components of the color space for the color.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the number of color components (including alpha) associated with a Quartz color.

    Declaration

    Swift

    func CGColorGetNumberOfComponents(_ color: CGColor!) -> Int

    Objective-C

    size_t CGColorGetNumberOfComponents ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    The number of color components (including alpha) associated with the specified color. This number is one more than the number of components of the color space for the color.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the pattern associated with a Quartz color in a pattern color space.

    Declaration

    Swift

    func CGColorGetPattern(_ color: CGColor!) -> CGPattern!

    Objective-C

    CGPatternRef CGColorGetPattern ( CGColorRef color );

    Parameters

    color

    A Quartz color.

    Return Value

    The pattern for the specified color. You are responsible for retaining and releasing the pattern as needed.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

  • Returns the Core Foundation type identifier for a Quartz color data type.

    Declaration

    Swift

    func CGColorGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGColorGetTypeID ( void );

    Return Value

    The Core Foundation type identifier for CGColorRef.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.3 and later.

Data Types

  • An opaque type that represents a color used in Quartz 2D drawing.

    Declaration

    Swift

    typealias CGColorRef = CGColor

    Objective-C

    typedef struct CGColor *CGColorRef;

    Discussion

    CGColorRef is the fundamental data type used internally by Quartz to represent colors. CGColor objects, and the functions that operate on them, provide a fast and convenient way of managing and setting colors directly, especially colors that are reused (such as black for text).

    In OS X version 10.3 and later, CGColorRef is derived from CFTypeRef and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

Constants

  • Commonly used colors.

    Declaration

    Swift

    let kCGColorWhite: CFString! let kCGColorBlack: CFString! let kCGColorClear: CFString!

    Objective-C

    const CFStringRef kCGColorWhite; const CFStringRef kCGColorBlack; const CFStringRef kCGColorClear;

    Constants

    • kCGColorWhite

      kCGColorWhite

      The white color in the Generic gray color space.

      Available in OS X v10.5 and later.

    • kCGColorBlack

      kCGColorBlack

      The black color in the Generic gray color space.

      Available in OS X v10.5 and later.

    • kCGColorClear

      kCGColorClear

      The clear color in the Generic gray color space.

      Available in OS X v10.5 and later.