iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UISwitch Class Reference

Options
Deployment Target:

On This Page
Language:

UISwitch

You use the UISwitch class to create and manage the On/Off buttons used, for example, in the Settings app for options such as Airplane Mode and Bluetooth. These objects are known as switches.

The UISwitch class declares a property and a method to control its on/off state. As with UISlider, when the user manipulates the switch control (“flips” it) a UIControlEventValueChanged event is generated, which results in the control (if properly configured) sending an action message.

You can customize the appearance of the switch by changing the color used to tint the switch when it is on or off.

For information about basic view behaviors, see View Programming Guide for iOS.

For more information about appearance and behavior configuration, see Switches.

  • init(frame:) - initWithFrame: Designated Initializer

    Returns an initialized switch object.

    Declaration

    Swift

    init(frame frame: CGRect)

    Objective-C

    - (instancetype nonnull)initWithFrame:(CGRect)frame

    Parameters

    frame

    A rectangle defining the frame of the UISwitch object. The size components of this rectangle are ignored.

    Return Value

    An initialized UISwitch object or nil if the object could not be initialized.

    Discussion

    UISwitch overrides initWithFrame: and enforces a size appropriate for the control.

    Availability

    Available in iOS 2.0 and later.

  • on on Property

    A Boolean value that determines the off/on state of the switch.

    Declaration

    Swift

    var on: Bool

    Objective-C

    @property(nonatomic, getter=isOn) BOOL on

    Discussion

    This property allows you to retrieve and set (without animation) a value determining whether the UISwitch object is on or off.

    Availability

    Available in iOS 2.0 and later.

  • Set the state of the switch to On or Off, optionally animating the transition.

    Declaration

    Swift

    func setOn(_ on: Bool, animated animated: Bool)

    Objective-C

    - (void)setOn:(BOOL)on animated:(BOOL)animated

    Parameters

    on

    YEStrue if the switch should be turned to the On position; NOfalse if it should be turned to the Off position. If the switch is already in the designated position, nothing happens.

    animated

    YEStrue to animate the “flipping” of the switch; otherwise NOfalse.

    Discussion

    Setting the switch to either position does not result in an action message being sent.

    Availability

    Available in iOS 2.0 and later.

  • The color used to tint the appearance of the switch when it is turned on.

    Declaration

    Swift

    var onTintColor: UIColor?

    Objective-C

    @property(nonatomic, strong) UIColor *onTintColor

    Availability

    Available in iOS 5.0 and later.

  • The color used to tint the outline of the switch when it is turned off.

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

    @property(nonatomic, strong) UIColor * __null_unspecified tintColor

    Availability

    Available in iOS 6.0 and later.

  • The color used to tint the appearance of the thumb.

    Declaration

    Swift

    var thumbTintColor: UIColor?

    Objective-C

    @property(nonatomic, strong) UIColor *thumbTintColor

    Availability

    Available in iOS 6.0 and later.

  • The image displayed when the switch is in the on position.

    Declaration

    Swift

    var onImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *onImage

    Discussion

    In iOS 7, this property has no effect.

    In iOS 6, this image represents the interior contents of the switch. The image you specify is composited with the switch’s rounded bezel and thumb to create the final appearance.

    Availability

    Available in iOS 6.0 and later.

  • The image displayed while the switch is in the off position.

    Declaration

    Swift

    var offImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *offImage

    Discussion

    In iOS 7, this property has no effect.

    In iOS 6, this image represents the interior contents of the switch. The image you specify is composited with the switch’s rounded bezel and thumb to create the final appearance.

    Availability

    Available in iOS 6.0 and later.