Class

UIColor

An object that stores color data and sometimes opacity (that is, alpha value).

Overview

objects can be created in a variety of ways:

The most common way to use a UIColor object is to provide it to some other object in UIKit. For example, the UIView class (and its descendants) include background and tint colors to affect how they are drawn onscreen. Listing 1 sets the background and tint color of a view.

Listing 1

Using a UIColor object to set the color of a view controller’s view

self.backgroundView.backgroundColor = UIColor.gray()
self.backgroundView.tintColor = UIColor.blue()

When performing custom drawing, a UIColor object provides methods that set the fill or stroke colors of the current graphics context. Listing 2 shows a simple example of custom drawing inside a view.

Listing 2

Using a UIColor object to perform custom drawing

class CircleView: UIView {
    
    override func draw(_ rect: CGRect) {
        let ovalBounds = self.bounds.insetBy(dx: 10, dy: 10)
        let oval = UIBezierPath(ovalIn: ovalBounds)
        let brightRed = UIColor(displayP3Red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
        brightRed.setFill()
        oval.fill()
    }
}

See Setting the Graphics Context’s Drawing Color for the complete list of functions.

Color and Color Spaces

A UIColor object is typically represented internally as a Core Graphics color (CGColor) in a Core Graphics color space (CGColor​Space). There are methods and properties that return the underlying color data. See Retrieving Color Information. When creating a custom color, the underlying color space and the range of values for each color component vary based on the iOS version.

On versions of iOS before iOS 10, and for apps linked on a version of iOS prior to iOS 10, colors are created and returned in one of two color spaces:

  • Device-Dependent Gray

  • Device-Dependent RGB

These device color spaces correspond closely to the display characteristics of the sRGB color space. Color component values within these color spaces are represented by values between 0.0 and 1.0. When a color is created, the input parameters are clamped to fit within this color space.

If your app was linked on or after iOS 10 and when running on iOS 10 or later, colors are created in extended color spaces:

  • k​CGColor​Space​Extended​Gray

  • k​CGColor​Space​Extended​SRGB

When working in an extended color space, color values are not clamped to fit inside the color gamut, meaning that component values may be less than 0.0 or greater than 1.0. When displayed on an sRGB display, such colors are outside the gamut and will not be rendered accurately. However, extended color spaces are useful working color spaces when you want a pixel format and representation that other color spaces can be easily converted into. For example, a color in the display P3 color space that is not within the sRGB color gamut can still be converted to an extended sRGB format. Some of its values will be outside of the 0.0 to 1.0 range. However, when displayed on a device with a P3 display gamut, it would still be rendered correctly.

To summarize, when you need to worry about color spaces, use these extended color spaces as working color spaces. When you need to worry about representing that color as closely as possible in a specific color space, convert the color from the extended color space into the target color space.

Subclassing Notes

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

Symbols

Creating System Colors

class var dark​Text:​ UIColor

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

class var light​Text:​ UIColor

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

class var group​Table​View​Background:​ UIColor

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

Creating a Color Object with a Predefined Color

class var black:​ UIColor

A color object in the sRGB color space whose grayscale value is 0.0 and whose alpha value is 1.0.

class var blue:​ UIColor

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

class var brown:​ UIColor

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

class var clear:​ UIColor

A color object whose grayscale and alpha values are both 0.0.

class var cyan:​ UIColor

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

class var dark​Gray:​ UIColor

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

class var gray:​ UIColor

A color object whose grayscale value is 0.5 and whose alpha value is 1.0.

class var green:​ UIColor

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

class var light​Gray:​ UIColor

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

class var magenta:​ UIColor

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

class var orange:​ UIColor

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

class var purple:​ UIColor

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

class var red:​ UIColor

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

class var white:​ UIColor

A color object whose grayscale value is 1.0 and whose alpha value is 1.0.

class var yellow:​ UIColor

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

Creating a Custom UIColor Object in a Specific Color Space

init(white:​ CGFloat, alpha:​ CGFloat)

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

init(hue:​ CGFloat, saturation:​ CGFloat, brightness:​ CGFloat, alpha:​ CGFloat)

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

init(red:​ CGFloat, green:​ CGFloat, blue:​ CGFloat, alpha:​ CGFloat)

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

init(display​P3Red:​ CGFloat, green:​ CGFloat, blue:​ CGFloat, alpha:​ CGFloat)

Initializes and returns a color object using the specified opacity and RGB component values in the Display P3 color space.

Creating a UIColor Object from another Representation of Color

init(ci​Color:​ CIColor)

Initializes and returns a color object that encapsulates a Core Image color.

init(cg​Color:​ CGColor)

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

func with​Alpha​Component(CGFloat)

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

Creating a UIColor Object that Draws Using a Pattern

init(pattern​Image:​ UIImage)

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

Setting the Graphics Context’s Drawing Color

func set()

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

func set​Fill()

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

func set​Stroke()

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