iOS Developer Library

Developer

UIKit Framework Reference UIControl Class Reference

Options
Deployment Target:

On This Page
Language:

UIControl

UIControl is the base class for control objects such as buttons and sliders that convey user intent to the application. You cannot use the UIControl class directly to instantiate controls. It instead defines the common interface and behavioral structure for all its subclasses.

The main role of UIControl is to define an interface and base implementation for preparing action messages and initially dispatching them to their targets when certain events occur.

For an overview of the target-action mechanism, see Target-Action in UIKit. For information on the Multi-Touch event model, see Event Handling Guide for iOS.

The UIControl class also includes methods for getting and setting control state—for example, for determining whether a control is enabled or highlighted—and it defines methods for tracking touches within a control. These tracking methods are overridden by UIControl subclasses.

Subclassing Notes

You may want to extend a UIControl subclass for either of two reasons:

For more information about appearance and behavior configuration, see About Controls.

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.
  • In response to a given event, forwards an action message to the application object for dispatching to a target.

    Declaration

    Swift

    func sendAction(_ action: Selector, to target: AnyObject?, forEvent event: UIEvent?)

    Objective-C

    - (void)sendAction:(SEL)action to:(id)target forEvent:(UIEvent *)event

    Parameters

    action

    A selector identifying an action message. It cannot be NULL.

    target

    The target object—that is, the object to which the action message is sent. If this is nil, the receiver traverses the responder chain and sends the action message to the first object willing to respond to it.

    event

    An object representing the event (typically in a UIControl object) that originated the action message. The event can be nil if the action is invoked directly instead of being caused by an event. For example, a value-changed message might be sent for programmatic reasons rather than as a result of the user touching the control.

    Discussion

    UIControl implements this method to forward an action message to the singleton UIApplication object (in its sendAction:to:fromSender:forEvent: method) for dispatching it to the target or, if there is no specified target, to the first object in the responder chain that is willing to handle it. Subclasses may override this method to observe or modify action-forwarding behavior. The implementation of sendActionsForControlEvents: might call this method repeatedly, once for each specified control event.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sends action messages for the given control events.

    Declaration

    Swift

    func sendActionsForControlEvents(_ controlEvents: UIControlEvents)

    Objective-C

    - (void)sendActionsForControlEvents:(UIControlEvents)controlEvents

    Parameters

    controlEvents

    A bitmask whose set flags specify the control events for which action messages are sent. See Control Events for bitmask constants.

    Discussion

    UIControl implements this method to send all action messages associated with controlEvents, repeatedly invoking sendAction:to:forEvent: in the process. The list of targets and actions it looks up is constructed from prior invocations of addTarget:action:forControlEvents:.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Adds a target and action for a particular event (or events) to an internal dispatch table.

    Declaration

    Swift

    func addTarget(_ target: AnyObject?, action action: Selector, forControlEvents controlEvents: UIControlEvents)

    Objective-C

    - (void)addTarget:(id)target action:(SEL)action forControlEvents:(UIControlEvents)controlEvents

    Parameters

    target

    The target object—that is, the object to which the action message is sent. If this is nil, the responder chain is searched for an object willing to respond to the action message.

    action

    A selector identifying an action message. It cannot be NULL.

    controlEvents

    A bitmask specifying the control events for which the action message is sent. See Control Events for bitmask constants.

    Discussion

    You may call this method multiple times, and you may specify multiple target-action pairs for a particular event. The action message may optionally include the sender and the event as parameters, in that order.

    When you call this method, target is not retained.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Removes a target and action for a particular event (or events) from an internal dispatch table.

    Declaration

    Swift

    func removeTarget(_ target: AnyObject?, action action: Selector, forControlEvents controlEvents: UIControlEvents)

    Objective-C

    - (void)removeTarget:(id)target action:(SEL)action forControlEvents:(UIControlEvents)controlEvents

    Parameters

    target

    The target object—that is, the object to which the action message is sent. Pass nil to remove all targets paired with action and the specified control events.

    action

    A selector identifying an action message. Pass NULL to remove all action messages paired with target.

    controlEvents

    A bitmask specifying the control events associated with target and action. See Control Events for bitmask constants.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns the actions that are associated with a target and a particular control event.

    Declaration

    Swift

    func actionsForTarget(_ target: AnyObject, forControlEvent controlEvent: UIControlEvents) -> [AnyObject]?

    Objective-C

    - (NSArray *)actionsForTarget:(id)target forControlEvent:(UIControlEvents)controlEvent

    Parameters

    target

    The target object—that is, the object to which an action message is sent.

    You must pass an explicit match for the target. Do not pass a value of nil.

    controlEvent

    A single constant of type UIControlEvents that specifies a particular user action on the control; for a list of these constants, see Control Events.

    Return Value

    An array of selector names as NSString objects or nil if there are no action selectors associated with the control event.

    Discussion

    Pass in a selector name to the NSSelectorFromString function to obtain the selector (SEL) value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns all target objects associated with the receiver.

    Declaration

    Swift

    func allTargets() -> NSSet

    Objective-C

    - (NSSet *)allTargets

    Return Value

    A set of all targets—that is, the objects to which action messages are sent—for the receiver. The set may include NSNull to indicate at least one nil target (meaning, the responder chain is searched for a target).

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns all control events associated with the receiver.

    Declaration

    Swift

    func allControlEvents() -> UIControlEvents

    Objective-C

    - (UIControlEvents)allControlEvents

    Return Value

    One or more UIControlEvents constants that specify the current control events associated with the receiver; for a list of these constants, see Control Eventslist of all events that have at least one action.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    – allTargets

  • state state Property

    A bitmask value that indicates the state of the receiver. (read-only)

    Declaration

    Swift

    var state: UIControlState { get }

    Objective-C

    @property(nonatomic, readonly) UIControlState state

    Discussion

    One or more UIControlState bit-mask constants that specify the state of the UIControl object; for information on these constants, see Control State. Note that the control can be in more than one state, for example, both disabled and selected (UIControlStateDisabled | UIControlStateSelected).This attribute is read only—there is no corresponding setter method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • enabled enabled Property

    A Boolean value that determines whether the receiver is enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Discussion

    Specify YEStrue to make the control enabled; otherwise, specify NOfalse to make it disabled. The default value is YEStrue. If the enabled state is NOfalse, the control ignores touch events and subclasses may draw differently.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    state

  • selected selected Property

    A Boolean value that determines the receiver’s selected state.

    Declaration

    Swift

    var selected: Bool

    Objective-C

    @property(nonatomic, getter=isSelected) BOOL selected

    Discussion

    Specify YEStrue if the control is selected; otherwise NOfalse. The default is NOfalse. For many controls, this state has no effect on behavior or appearance. But other subclasses (for example, UISwitchControl) or the application object might read or set this control state.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    state

  • A Boolean value that determines whether the receiver is highlighted.

    Declaration

    Swift

    var highlighted: Bool

    Objective-C

    @property(nonatomic, getter=isHighlighted) BOOL highlighted

    Discussion

    Specify YEStrue if the control is highlighted; otherwise NOfalse. By default, a control is not highlighted. UIControl automatically sets and clears this state automatically when a touch enters and exits during tracking and when there is a touch up.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    state

  • The vertical alignment of content (text or image) within the receiver.

    Declaration

    Swift

    var contentVerticalAlignment: UIControlContentVerticalAlignment

    Objective-C

    @property(nonatomic) UIControlContentVerticalAlignment contentVerticalAlignment

    Parameters

    contentAlignment

    A constant that specifies the alignment of text or image within the receiver. See Vertical Content Alignment for descriptions of valid constants.

    Discussion

    This value of this property is a constant that specifies the alignment of text or image within the receiver. The default is UIControlContentVerticalAlignmentTop.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The horizontal alignment of content (text or image) within the receiver.

    Declaration

    Swift

    var contentHorizontalAlignment: UIControlContentHorizontalAlignment

    Objective-C

    @property(nonatomic) UIControlContentHorizontalAlignment contentHorizontalAlignment

    Parameters

    contentAlignment

    A constant that specifies the alignment of text or image within the receiver. See Horizontal Content Alignment for descriptions of valid constants.

    Discussion

    The value of this property is a constant that specifies the alignment of text or image within the receiver. The default is UIControlContentHorizontalAlignmentLeft.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sent to the control when a touch related to the given event enters the control’s bounds.

    Declaration

    Swift

    func beginTrackingWithTouch(_ touch: UITouch, withEvent event: UIEvent) -> Bool

    Objective-C

    - (BOOL)beginTrackingWithTouch:(UITouch *)touch withEvent:(UIEvent *)event

    Parameters

    touch

    A UITouch object that represents a touch on the receiving control during tracking.

    event

    An event object encapsulating the information specific to the user event.

    Return Value

    YEStrue if the receiver is set to respond continuously or set to respond when a touch is dragged; otherwise NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sent continuously to the control as it tracks a touch related to the given event within the control’s bounds.

    Declaration

    Swift

    func continueTrackingWithTouch(_ touch: UITouch, withEvent event: UIEvent) -> Bool

    Objective-C

    - (BOOL)continueTrackingWithTouch:(UITouch *)touch withEvent:(UIEvent *)event

    Parameters

    touch

    A UITouch object that represents a touch on the receiving control during tracking.

    event

    An event object encapsulating the information specific to the user event

    Return Value

    YEStrue if touch tracking should continue; otherwise NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Sent to the control when the last touch for the given event completely ends, telling it to stop tracking.

    Declaration

    Swift

    func endTrackingWithTouch(_ touches: UITouch, withEvent event: UIEvent)

    Objective-C

    - (void)endTrackingWithTouch:(UITouch *)touches withEvent:(UIEvent *)event

    Parameters

    touches

    A UITouch object that represents a touch on the receiving control during tracking.

    event

    An event object encapsulating the information specific to the user event.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Tells the control to cancel tracking related to the given event.

    Declaration

    Swift

    func cancelTrackingWithEvent(_ event: UIEvent?)

    Objective-C

    - (void)cancelTrackingWithEvent:(UIEvent *)event

    Parameters

    event

    An event object encapsulating the information specific to the user event. This parameter might be nil, indicating that the cancelation was caused by something other than an event, such as the view being removed from the window.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • tracking tracking Property

    A Boolean value that indicates whether the receiver is currently tracking touches related to an event. (read-only)

    Declaration

    Swift

    var tracking: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isTracking) BOOL tracking

    Discussion

    The value is YEStrue if the receiver is tracking touches; otherwiseNOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that indicates whether a touch is inside the bounds of the receiver. (read-only)

    Declaration

    Swift

    var touchInside: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isTouchInside) BOOL touchInside

    Return Value

    YEStrue if a touch is inside the receiver’s bounds; otherwise NOfalse.

    Discussion

    The value is YEStrue if a touch is inside the receiver’s bounds; otherwise the value is NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

Data Types

  • Kinds of events possible for control objects.

    Declaration

    Swift

    struct UIControlEvents : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var TouchDown: UIControlEvents { get } static var TouchDownRepeat: UIControlEvents { get } static var TouchDragInside: UIControlEvents { get } static var TouchDragOutside: UIControlEvents { get } static var TouchDragEnter: UIControlEvents { get } static var TouchDragExit: UIControlEvents { get } static var TouchUpInside: UIControlEvents { get } static var TouchUpOutside: UIControlEvents { get } static var TouchCancel: UIControlEvents { get } static var ValueChanged: UIControlEvents { get } static var EditingDidBegin: UIControlEvents { get } static var EditingChanged: UIControlEvents { get } static var EditingDidEnd: UIControlEvents { get } static var EditingDidEndOnExit: UIControlEvents { get } static var AllTouchEvents: UIControlEvents { get } static var AllEditingEvents: UIControlEvents { get } static var ApplicationReserved: UIControlEvents { get } static var SystemReserved: UIControlEvents { get } static var AllEvents: UIControlEvents { get } }

    Objective-C

    enum { UIControlEventTouchDown = 1 << 0, UIControlEventTouchDownRepeat = 1 << 1, UIControlEventTouchDragInside = 1 << 2, UIControlEventTouchDragOutside = 1 << 3, UIControlEventTouchDragEnter = 1 << 4, UIControlEventTouchDragExit = 1 << 5, UIControlEventTouchUpInside = 1 << 6, UIControlEventTouchUpOutside = 1 << 7, UIControlEventTouchCancel = 1 << 8, UIControlEventValueChanged = 1 << 12, UIControlEventEditingDidBegin = 1 << 16, UIControlEventEditingChanged = 1 << 17, UIControlEventEditingDidEnd = 1 << 18, UIControlEventEditingDidEndOnExit = 1 << 19, UIControlEventAllTouchEvents = 0x00000FFF, UIControlEventAllEditingEvents = 0x000F0000, UIControlEventApplicationReserved = 0x0F000000, UIControlEventSystemReserved = 0xF0000000, UIControlEventAllEvents = 0xFFFFFFFF };

    Constants

    • TouchDown

      UIControlEventTouchDown

      A touch-down event in the control.

      Available in iOS 2.0 and later.

    • TouchDownRepeat

      UIControlEventTouchDownRepeat

      A repeated touch-down event in the control; for this event the value of the UITouch tapCount method is greater than one.

      Available in iOS 2.0 and later.

    • TouchDragInside

      UIControlEventTouchDragInside

      An event where a finger is dragged inside the bounds of the control.

      Available in iOS 2.0 and later.

    • TouchDragOutside

      UIControlEventTouchDragOutside

      An event where a finger is dragged just outside the bounds of the control.

      Available in iOS 2.0 and later.

    • TouchDragEnter

      UIControlEventTouchDragEnter

      An event where a finger is dragged into the bounds of the control.

      Available in iOS 2.0 and later.

    • TouchDragExit

      UIControlEventTouchDragExit

      An event where a finger is dragged from within a control to outside its bounds.

      Available in iOS 2.0 and later.

    • TouchUpInside

      UIControlEventTouchUpInside

      A touch-up event in the control where the finger is inside the bounds of the control.

      Available in iOS 2.0 and later.

    • TouchUpOutside

      UIControlEventTouchUpOutside

      A touch-up event in the control where the finger is outside the bounds of the control.

      Available in iOS 2.0 and later.

    • TouchCancel

      UIControlEventTouchCancel

      A system event canceling the current touches for the control.

      Available in iOS 2.0 and later.

    • ValueChanged

      UIControlEventValueChanged

      A touch dragging or otherwise manipulating a control, causing it to emit a series of different values.

      Available in iOS 2.0 and later.

    • EditingDidBegin

      UIControlEventEditingDidBegin

      A touch initiating an editing session in a UITextField object by entering its bounds.

      Available in iOS 2.0 and later.

    • EditingChanged

      UIControlEventEditingChanged

      A touch making an editing change in a UITextField object.

      Available in iOS 2.0 and later.

    • EditingDidEnd

      UIControlEventEditingDidEnd

      A touch ending an editing session in a UITextField object by leaving its bounds.

      Available in iOS 2.0 and later.

    • EditingDidEndOnExit

      UIControlEventEditingDidEndOnExit

      A touch ending an editing session in a UITextField object.

      Available in iOS 2.0 and later.

    • AllTouchEvents

      UIControlEventAllTouchEvents

      All touch events.

      Available in iOS 2.0 and later.

    • AllEditingEvents

      UIControlEventAllEditingEvents

      All editing touches for UITextField objects.

      Available in iOS 2.0 and later.

    • ApplicationReserved

      UIControlEventApplicationReserved

      A range of control-event values available for application use.

      Available in iOS 2.0 and later.

    • SystemReserved

      UIControlEventSystemReserved

      A range of control-event values reserved for internal framework use.

      Available in iOS 2.0 and later.

    • AllEvents

      UIControlEventAllEvents

      All events, including system events.

      Available in iOS 2.0 and later.

    Discussion

    You set up a control so that it sends an action message to a target object by associating both target and action with one or more control events. To do this, send addTarget:action:forControlEvents:: to the control for each target-action pair you want to specify.

  • The vertical alignment of content (text and images) within a control.

    Declaration

    Swift

    enum UIControlContentVerticalAlignment : Int { case Center case Top case Bottom case Fill }

    Objective-C

    typedef enum { UIControlContentVerticalAlignmentCenter = 0, UIControlContentVerticalAlignmentTop = 1, UIControlContentVerticalAlignmentBottom = 2, UIControlContentVerticalAlignmentFill = 3, } UIControlContentVerticalAlignment;

    Constants

    • Center

      UIControlContentVerticalAlignmentCenter

      Aligns the content vertically in the center of the control.

      Available in iOS 2.0 and later.

    • Top

      UIControlContentVerticalAlignmentTop

      Aligns the content vertically at the top in the control (the default).

      Available in iOS 2.0 and later.

    • Bottom

      UIControlContentVerticalAlignmentBottom

      Aligns the content vertically at the bottom in the control

      Available in iOS 2.0 and later.

    • Fill

      UIControlContentVerticalAlignmentFill

      Aligns the content vertically to fill the content rectangle; images may be stretched.

      Available in iOS 2.0 and later.

    Discussion

    You use these constants as the value of the contentVerticalAlignment property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The horizontal alignment of content (text and images) within a control.

    Declaration

    Swift

    enum UIControlContentHorizontalAlignment : Int { case Center case Left case Right case Fill }

    Objective-C

    typedef enum { UIControlContentHorizontalAlignmentCenter = 0, UIControlContentHorizontalAlignmentLeft = 1, UIControlContentHorizontalAlignmentRight = 2, UIControlContentHorizontalAlignmentFill = 3, } UIControlContentHorizontalAlignment;

    Constants

    • Center

      UIControlContentHorizontalAlignmentCenter

      Aligns the content horizontally in the center of the control.

      Available in iOS 2.0 and later.

    • Left

      UIControlContentHorizontalAlignmentLeft

      Aligns the content horizontally from the left of the control (the default).

      Available in iOS 2.0 and later.

    • Right

      UIControlContentHorizontalAlignmentRight

      Aligns the content horizontally from the right of the control

      Available in iOS 2.0 and later.

    • Fill

      UIControlContentHorizontalAlignmentFill

      Aligns the content horizontally to fill the content rectangles; text may wrap and images may be stretched.

      Available in iOS 2.0 and later.

    Discussion

    You use these constants as the value of the contentHorizontalAlignment property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The state of a control; a control can have more than one state at a time. States are recognized differently depending on the control. For example, a UIButton instance may be configured (using the setImage:forState: method) to display one image when it is in its normal state and a different image when it is highlighted.

    Declaration

    Swift

    struct UIControlState : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Normal: UIControlState { get } static var Highlighted: UIControlState { get } static var Disabled: UIControlState { get } static var Selected: UIControlState { get } static var Application: UIControlState { get } static var Reserved: UIControlState { get } }

    Objective-C

    enum { UIControlStateNormal = 0, UIControlStateHighlighted = 1 << 0, UIControlStateDisabled = 1 << 1, UIControlStateSelected = 1 << 2, UIControlStateApplication = 0x00FF0000, UIControlStateReserved = 0xFF000000 };

    Constants

    • Normal

      UIControlStateNormal

      The normal, or default state of a control—that is, enabled but neither selected nor highlighted.

      Available in iOS 2.0 and later.

    • Highlighted

      UIControlStateHighlighted

      Highlighted state of a control. A control enters this state when a touch enters and exits during tracking and when there is a touch up event. You can retrieve and set this value through the highlighted property.

      Available in iOS 2.0 and later.

    • Disabled

      UIControlStateDisabled

      Disabled state of a control. This state indicates that the control is currently disabled. You can retrieve and set this value through the enabled property.

      Available in iOS 2.0 and later.

    • Selected

      UIControlStateSelected

      Selected state of a control. For many controls, this state has no effect on behavior or appearance. But other subclasses (for example, the UISegmentedControl class) may have different appearance depending on their selected state. You can retrieve and set this value through the selected property.

      Available in iOS 2.0 and later.

    • Application

      UIControlStateApplication

      Additional control-state flags available for application use.

      Available in iOS 2.0 and later.

    • Reserved

      UIControlStateReserved

      Control-state flags reserved for internal framework use.

      Available in iOS 2.0 and later.