UIColor Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIColor.h
UIInterface.h
Related sample code

Overview

A UIColor object represents color and sometimes opacity (alpha value). You can use UIColor objects to store color data, and during drawing you can use them to set the current fill and stroke colors.

Many methods in UIKit require you to specify color data using a UIColor object, and for general color needs it should be your main way of specifying colors. The color spaces used by this object are optimized for use on iOS-based devices and are therefore appropriate for most drawing needs. If you prefer to use Core Graphics colors and color spaces instead, however, you may do so.

Color objects are immutable and so it is safe to use them from multiple threads in your app.

Most developers should have no need to subclass UIColor. The only time doing so might be necessary is if you require support for additional colorspaces or color models. If you do subclass, the properties and methods you add must also be safe to use from multiple threads.

Tasks

Creating a UIColor Object from Component Values

Initializing a UIColor Object

Creating a UIColor with Preset Component Values

System Colors

Retrieving Color Information

Drawing Operations

Properties

CGColor

The Quartz color reference that corresponds to the receiver’s color. (read-only)

@property(nonatomic, readonly) CGColorRef CGColor
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

CIColor

The Core Image color associated with the receiver. (read-only)

@property(nonatomic, readonly) CIColor *CIColor
Discussion

This property throws an exception if the color object was not initialized with a Core Image color.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIColor.h

Class Methods

blackColor

Returns a color object whose grayscale value is 0.0 and whose alpha value is 1.0.

+ (UIColor *)blackColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

blueColor

Returns a color object whose RGB values are 0.0, 0.0, and 1.0 and whose alpha value is 1.0.

+ (UIColor *)blueColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

brownColor

Returns a color object whose RGB values are 0.6, 0.4, and 0.2 and whose alpha value is 1.0.

+ (UIColor *)brownColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

clearColor

Returns a color object whose grayscale and alpha values are both 0.0.

+ (UIColor *)clearColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

colorWithCGColor:

Creates and returns a color object using the specified Quartz color reference.

+ (UIColor *)colorWithCGColor:(CGColorRef)cgColor
Parameters
cgColor

A reference to a Quartz color.

Return Value

The color object. The color information represented by this object is in the native colorspace of the specified Quartz color.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

colorWithCIColor:

Converts a Core Image color object to its UIColor equivalent

+ (UIColor *)colorWithCIColor:(CIColor *)ciColor
Parameters
ciColor

The Core Image color to convert.

Return Value

The UIColor object corresponding to the specified Core Image color.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UIColor.h

colorWithHue:saturation:brightness:alpha:

Creates and returns a color object using the specified opacity and HSB color space component values.

+ (UIColor *)colorWithHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha
Parameters
hue

The hue component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

saturation

The saturation component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

brightness

The brightness (or value) component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

The color object. The color information represented by this object is in the device RGB colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

colorWithPatternImage:

Creates and returns a color object using the specified image.

+ (UIColor *)colorWithPatternImage:(UIImage *)image
Parameters
image

The image to use when creating the pattern color.

Return Value

The pattern color.

Discussion

You can use pattern colors to set the fill or stroke color just as you would a solid color. During drawing, the image in the pattern color is tiled as necessary to cover the given area.

By default, the phase of the returned color is 0, which causes the top-left corner of the image to be aligned with the drawing origin. To change the phase, make the color the current color and then use the CGContextSetPatternPhase function to change the phase.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

colorWithRed:green:blue:alpha:

Creates and returns a color object using the specified opacity and RGB component values.

+ (UIColor *)colorWithRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha
Parameters
red

The red component of the color object, specified as a value from 0.0 to 1.0.

green

The green component of the color object, specified as a value from 0.0 to 1.0.

blue

The blue component of the color object, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

The color object. The color information represented by this object is in the device RGB colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

colorWithWhite:alpha:

Creates and returns a color object using the specified opacity and grayscale values.

+ (UIColor *)colorWithWhite:(CGFloat)white alpha:(CGFloat)alpha
Parameters
white

The grayscale value of the color object, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

The color object. The color information represented by this object is in the device gray colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

cyanColor

Returns a color object whose RGB values are 0.0, 1.0, and 1.0 and whose alpha value is 1.0.

+ (UIColor *)cyanColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

darkGrayColor

Returns a color object whose grayscale value is 1/3 and whose alpha value is 1.0.

+ (UIColor *)darkGrayColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

darkTextColor

Returns the system color used for displaying text on a light background.

+ (UIColor *)darkTextColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIInterface.h

grayColor

Returns a color object whose grayscale value is 0.5 and whose alpha value is 1.0.

+ (UIColor *)grayColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

greenColor

Returns a color object whose RGB values are 0.0, 1.0, and 0.0 and whose alpha value is 1.0.

+ (UIColor *)greenColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

groupTableViewBackgroundColor

Returns the system color used for the background of a grouped table.

+ (UIColor *)groupTableViewBackgroundColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIInterface.h

lightGrayColor

Returns a color object whose grayscale value is 2/3 and whose alpha value is 1.0.

+ (UIColor *)lightGrayColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

lightTextColor

Returns the system color used for displaying text on a dark background.

+ (UIColor *)lightTextColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIInterface.h

magentaColor

Returns a color object whose RGB values are 1.0, 0.0, and 1.0 and whose alpha value is 1.0.

+ (UIColor *)magentaColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

orangeColor

Returns a color object whose RGB values are 1.0, 0.5, and 0.0 and whose alpha value is 1.0.

+ (UIColor *)orangeColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

purpleColor

Returns a color object whose RGB values are 0.5, 0.0, and 0.5 and whose alpha value is 1.0.

+ (UIColor *)purpleColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

redColor

Returns a color object whose RGB values are 1.0, 0.0, and 0.0 and whose alpha value is 1.0.

+ (UIColor *)redColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

scrollViewTexturedBackgroundColor

Returns the system pattern color used to render the area behind scrollable content.

+ (UIColor *)scrollViewTexturedBackgroundColor
Return Value

The UIColor object.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIInterface.h

underPageBackgroundColor

Returns the system pattern color used to render the background of a page.

+ (UIColor *)underPageBackgroundColor
Return Value

The UIColor object.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIInterface.h

viewFlipsideBackgroundColor

Returns the system color used for the back side of a view while it is being flipped.

+ (UIColor *)viewFlipsideBackgroundColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIInterface.h

whiteColor

Returns a color object whose grayscale value is 1.0 and whose alpha value is 1.0.

+ (UIColor *)whiteColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

yellowColor

Returns a color object whose RGB values are 1.0, 1.0, and 0.0 and whose alpha value is 1.0.

+ (UIColor *)yellowColor
Return Value

The UIColor object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

Instance Methods

colorWithAlphaComponent:

Creates and returns a color object that has the same color space and component values as the receiver, but has the specified alpha component.

- (UIColor *)colorWithAlphaComponent:(CGFloat)alpha
Parameters
alpha

The opacity value of the new UIColor object.

Return Value

The new UIColor object.

Discussion

A subclass with explicit opacity components should override this method to return a color with the specified alpha.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIColor.h

getHue:saturation:brightness:alpha:

Returns the components that make up the color in the HSB color space.

- (BOOL)getHue:(CGFloat *)hue saturation:(CGFloat *)saturation brightness:(CGFloat *)brightness alpha:(CGFloat *)alpha
Parameters
hue

On return, the hue component of the color object, specified as a value between 0.0 and 1.0.

saturation

On return, the saturation component of the color object, specified as a value between 0.0 and 1.0.

brightness

On return, the brightness component of the color object, specified as a value between 0.0 and 1.0.

alpha

On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

Return Value

YES if the color could be converted, NO otherwise.

Discussion

If the color is in a compatible color space, the color is converted into the HSB color space and its components are returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIColor.h

getRed:green:blue:alpha:

Returns the components that make up the color in the RGB color space.

- (BOOL)getRed:(CGFloat *)red green:(CGFloat *)green blue:(CGFloat *)blue alpha:(CGFloat *)alpha
Parameters
red

On return, the red component of the color object, specified as a value between 0.0 and 1.0.

green

On return, the green component of the color object, specified as a value between 0.0 and 1.0.

blue

On return, the blue component of the color object, specified as a value between 0.0 and 1.0.

alpha

On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

Return Value

YES if the color could be converted, NO otherwise.

Discussion

If the color is in a compatible color space, the color is converted into RGB format and its components are returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIColor.h

getWhite:alpha:

Returns the grayscale components of the color.

- (BOOL)getWhite:(CGFloat *)white alpha:(CGFloat *)alpha
Parameters
white

On return, the grayscale component of the color object, specified as a value between 0.0 and 1.0.

alpha

On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

Return Value

YES if the color could be converted, NO otherwise.

Discussion

If the color is in a compatible color space, the color is converted into grayscale format and returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIColor.h

initWithCGColor:

Initializes and returns a color object using the specified Quartz color reference.

- (UIColor *)initWithCGColor:(CGColorRef)cgColor
Parameters
cgColor

A reference to a Quartz color.

Return Value

An initialized color object. The color information represented by this object is in the native colorspace of the specified Quartz color.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIColor.h

initWithCIColor:

Initializes and returns a color object using the specified Core Image color.

- (UIColor *)initWithCIColor:(CIColor *)ciColor
Parameters
ciColor

The Core Image color to convert.

Return Value

An initialized color object.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIColor.h

initWithHue:saturation:brightness:alpha:

Initializes and returns a color object using the specified opacity and HSB color space component values.

- (UIColor *)initWithHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha
Parameters
hue

The hue component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

saturation

The saturation component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

brightness

The brightness (or value) component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

An initialized color object. The color information represented by this object is in the device RGB colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIColor.h

initWithPatternImage:

Initializes and returns a color object using the specified Quartz color reference.

- (UIColor *)initWithPatternImage:(UIImage *)image
Parameters
image

The image to use when creating the pattern color.

Return Value

The pattern color.

Discussion

You can use pattern colors to set the fill or stroke color just as you would a solid color. During drawing, the image in the pattern color is tiled as necessary to cover the given area.

By default, the phase of the returned color is 0, which causes the top-left corner of the image to be aligned with the drawing origin. To change the phase, make the color the current color and then use the CGContextSetPatternPhase function to change the phase.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIColor.h

initWithRed:green:blue:alpha:

Initializes and returns a color object using the specified opacity and RGB component values.

- (UIColor *)initWithRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha
Parameters
red

The red component of the color object, specified as a value from 0.0 to 1.0.

green

The green component of the color object, specified as a value from 0.0 to 1.0.

blue

The blue component of the color object, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

An initialized color object. The color information represented by this object is in the device RGB colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

initWithWhite:alpha:

Initializes and returns a color object using the specified opacity and grayscale values.

- (UIColor *)initWithWhite:(CGFloat)white alpha:(CGFloat)alpha
Parameters
white

The grayscale value of the color object, specified as a value from 0.0 to 1.0.

alpha

The opacity value of the color object, specified as a value from 0.0 to 1.0.

Return Value

An initialized color object. The color information represented by this object is in the device gray colorspace.

Discussion

Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIColor.h

set

Sets the color of subsequent stroke and fill operations to the color that the receiver represents.

- (void)set
Discussion

If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify both the stroke and fill color in the current graphics context by setting them both to the color represented by the receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

setFill

Sets the color of subsequent fill operations to the color that the receiver represents.

- (void)setFill
Discussion

If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify the fill color in the current graphics context by setting it to the color represented by the receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h

setStroke

Sets the color of subsequent stroke operations to the color that the receiver represents.

- (void)setStroke
Discussion

If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify the stroke color in the current graphics context by setting it to the color represented by the receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIColor.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...