UIControl Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UIControl.h
Related sample code

Overview

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” in Cocoa Fundamentals Guide. 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”.

Tasks

Preparing and Sending Action Messages

Setting and Getting Control Attributes

Tracking Touches and Redrawing Controls

Properties

contentHorizontalAlignment

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

@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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIControl.h

contentVerticalAlignment

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

@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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIControl.h

enabled

A Boolean value that determines whether the receiver is enabled.

@property(nonatomic, getter=isEnabled) BOOL enabled
Discussion

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

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIControl.h

highlighted

A Boolean value that determines whether the receiver is highlighted.

@property(nonatomic, getter=isHighlighted) BOOL highlighted
Discussion

Specify YES if the control is highlighted; otherwise NO. 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.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIControl.h

selected

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

@property(nonatomic, getter=isSelected) BOOL selected
Discussion

Specify YES if the control is selected; otherwise NO. The default is NO. 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.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIControl.h

state

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

@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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

touchInside

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

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

YES if a touch is inside the receiver’s bounds; otherwise NO.

Discussion

The value is YES if a touch is inside the receiver’s bounds; otherwise the value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

tracking

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

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

The value is YES if the receiver is tracking touches; otherwiseNO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

Instance Methods

actionsForTarget:forControlEvent:

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

- (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

addTarget:action:forControlEvents:

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

- (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

allControlEvents

Returns all control events associated with the receiver.

- (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 Events”list of all events that have at least one action.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

allTargets

Returns all target objects associated with the receiver.

- (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).

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

beginTrackingWithTouch:withEvent:

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

- (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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

cancelTrackingWithEvent:

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

- (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

continueTrackingWithTouch:withEvent:

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

- (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

YES if touch tracking should continue; otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

endTrackingWithTouch:withEvent:

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

- (void)endTrackingWithTouch:(UITouch *)touch 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

removeTarget:action:forControlEvents:

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

- (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

sendAction:to:forEvent:

In response to a given event, forwards an action message to the application object for dispatching to a target.

- (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

sendActionsForControlEvents:

Sends action messages for the given control events.

- (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:.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

Constants

UIControlEvents

The type for the enum constants listed in “Control Events.”

typedef NSUInteger UIControlEvents;
Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h

Control Events

Kinds of events possible for control objects.

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
UIControlEventTouchDown

A touch-down event in the control.

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Declared in UIControl.h.

UIControlEventTouchDragInside

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventTouchDragOutside

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventTouchDragEnter

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventTouchDragExit

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Declared in UIControl.h.

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.

Declared in UIControl.h.

UIControlEventTouchCancel

A system event canceling the current touches for the control.

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Declared in UIControl.h.

UIControlEventEditingDidBegin

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventEditingChanged

A touch making an editing change in a UITextField objet.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventEditingDidEnd

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventEditingDidEndOnExit

A touch ending an editing session in a UITextField object.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventAllTouchEvents

All touch events.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventAllEditingEvents

All editing touches for UITextField objects.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventApplicationReserved

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventSystemReserved

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlEventAllEvents

All events, including system events.

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Vertical Content Alignment

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

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

Aligns the content vertically in the center of the control.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlContentVerticalAlignmentTop

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlContentVerticalAlignmentBottom

Aligns the content vertically at the bottom in the control

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlContentVerticalAlignmentFill

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

Discussion

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

Horizontal Content Alignment

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

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

Aligns the content horizontally in the center of the control.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlContentHorizontalAlignmentLeft

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlContentHorizontalAlignmentRight

Aligns the content horizontally from the right of the control

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Declared in UIControl.h.

Discussion

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

Control State

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.

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

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

Available in iOS 2.0 and later.

Declared in UIControl.h.

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.

Declared in UIControl.h.

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.

Declared in UIControl.h.

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.

Declared in UIControl.h.

UIControlStateApplication

Additional control-state flags available for application use.

Available in iOS 2.0 and later.

Declared in UIControl.h.

UIControlStateReserved

Control-state flags reserved for internal framework use.

Available in iOS 2.0 and later.

Declared in UIControl.h.

Declared In
UITouch.h

UIControlState

The bit-mask type for control-state constants.

typedef NSUInteger UIControlState;
Discussion

The constants are listed in “Control State.” Use the state property to retrieve the current state bits set for a control.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIControl.h