Class

UIColor

A UIColor object stores color data and sometimes opacity (alpha value). Many methods in UIKit require you to specify color data using a UIColor object; when drawing you use them to set the current fill and stroke colors. Color objects are immutable and can be used safely from multiple threads in your app.

Overview

UIColor 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 (CGColorSpace). 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:

  • kCGColorSpaceExtendedGray

  • kCGColorSpaceExtendedSRGB

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 spacs. 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 colorspaces or color models. If you do subclass, the properties and methods you add must also be safe to use from multiple threads.

Symbols

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(displayP3Red: 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(ciColor: CIColor)

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

init(cgColor: CGColor)

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

func withAlphaComponent(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(patternImage: 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 setFill()

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

func setStroke()

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

Instance Properties

var cgColor: CGColor

The Quartz color reference that corresponds to the receiver’s color.

Relationships

Inherits From