iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIAppearance Protocol Reference

Options
Deployment Target:

On This Page
Language:

UIAppearance

Inheritance


Not Applicable

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 5.0 and later.

Use the UIAppearance protocol to get the appearance proxy for a class. You can customize the appearance of instances of a class by sending appearance modification messages to the class’s appearance proxy.

There are two ways to customize appearance for objects: for all instances, and for instances contained within an instance of a container class.

  • To customize the appearance of all instances of a class, use appearance to get the appearance proxy for the class. For example, to modify the bar background tint color for all instances of UINavigationBar:

    • [[UINavigationBar appearance] setBarTintColor:myNavBarBackgroundColor];
  • To customize the appearances for instances of a class when contained within an instance of a container class, or instances in a hierarchy, use appearanceWhenContainedIn: to get the appearance proxy for the class. For example, to modify the appearance of bar buttons, based on the object that contains the navigation bar:

    • [[UIBarButtonItem appearanceWhenContainedIn:[UINavigationBar class], nil]
    • setBackgroundImage:myNavBarButtonBackgroundImage forState:state barMetrics:metrics];
    • [[UIBarButtonItem appearanceWhenContainedIn:[UINavigationBar class], [UIPopoverController class], nil]
    • setBackgroundImage:myPopoverNavBarButtonBackgroundImage forState:state barMetrics:metrics];
    • [[UIBarButtonItem appearanceWhenContainedIn:[UIToolbar class], nil]
    • setBackgroundImage:myToolbarButtonBackgroundImage forState:state barMetrics:metrics];
    • [[UIBarButtonItem appearanceWhenContainedIn:[UIToolbar class], [UIPopoverController class], nil]
    • setBackgroundImage:myPopoverToolbarButtonBackgroundImage forState:state barMetrics:metrics];

In any given view hierarchy, the outermost appearance proxy wins. Specificity (depth of the chain) is the tie-breaker. In other words, the containment statement in appearanceWhenContainedIn: is treated as a partial ordering. Given a concrete ordering (actual subview hierarchy), UIKit selects the partial ordering that is the first unique match when reading the actual hierarchy from the window down.

You can further refine which instances of a class will have their appearance customized by specifying a trait collection. Use the appearanceForTraitCollection: and appearanceForTraitCollection:whenContainedIn: methods to retrieve the proxy for a class with the specified trait collection.

To support appearance customization, a class must conform to the UIAppearanceContainer protocol and relevant accessor methods must be marked with UI_APPEARANCE_SELECTOR.

  • Returns the appearance proxy for the receiver. (required)

    Declaration

    Swift

    static func appearance() -> Self

    Objective-C

    + (instancetype)appearance

    Return Value

    The appearance proxy for the receiver.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Returns the appearance proxy for the receiver that has the passed trait collection. (required)

    Declaration

    Swift

    static func appearanceForTraitCollection(_ trait: UITraitCollection) -> Self

    Objective-C

    + (instancetype)appearanceForTraitCollection:(UITraitCollection *)trait

    Parameters

    trait

    The trait collection used for matching.

    Return Value

    The appearance proxy for the receiver.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Returns the appearance proxy for the receiver in a given containment hierarchy that has the passed trait collection. (required)

    Declaration

    Objective-C

    + (instancetype)appearanceForTraitCollection:(UITraitCollection *)trait whenContainedIn:(Class<UIAppearanceContainer>)ContainerClass, ...

    Parameters

    trait

    The trait collection used for matching.

    ContainerClass,

    A nil-terminated list of appearance container classes.

    Return Value

    The appearance proxy for the receiver in a given containment hierarchy.

    Discussion

    This method throws an exception for any item in the var-args list that is not a Class object that conforms to the UIAppearanceContainer protocol.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 8.0 and later.

  • Returns the appearance proxy for the receiver in a given containment hierarchy. (required)

    Declaration

    Objective-C

    + (instancetype)appearanceWhenContainedIn:(Class<UIAppearanceContainer>)ContainerClass, ...

    Parameters

    ContainerClass,

    A nil-terminated list of appearance container classes.

    Return Value

    The appearance proxy for the receiver in a given containment hierarchy.

    Discussion

    This method throws an exception for any item in the var-args list that is not a Class object that conforms to the UIAppearanceContainer protocol.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 5.0 and later.