UIControl Class Reference

Inherits from	UIView : UIResponder : NSObject
Conforms to	NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) NSObject (NSObject)
Framework	/System/Library/Frameworks/UIKit.framework
Availability	Available in iOS 2.0 and later.
Declared in	UIControl.h
Related sample code	Formulaic MapCallouts Regions UICatalog

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:

To observe or modify the dispatch of action messages to targets for particular events
To do this, override sendAction:to:forEvent:, evaluate the passed-in selector, target object, or UIControlEvents bit mask, and proceed as required.
To provide custom tracking behavior (for example, to change the highlight appearance)
To do this, override one or all of the following methods: beginTrackingWithTouch:withEvent:, continueTrackingWithTouch:withEvent:, endTrackingWithTouch:withEvent:.

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.

Related Sample Code

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.

Related Sample Code

iPhoneCoreDataRecipes

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.

Related Sample Code

Declared In

UIControl.h

state

A Boolean 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.

Related Sample Code

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

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

UIControl Class Reference

Overview

Subclassing Notes

Tasks

Preparing and Sending Action Messages

Setting and Getting Control Attributes

Tracking Touches and Redrawing Controls

Properties

contentHorizontalAlignment

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

contentVerticalAlignment

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

enabled

Discussion

Availability

See Also

Related Sample Code

Declared In

highlighted

Discussion

Availability

See Also

Related Sample Code

Declared In

selected

Discussion

Availability

See Also

Related Sample Code

Declared In

state

Discussion

Availability

See Also

Declared In

touchInside

Return Value

Discussion

Availability

Declared In

tracking

Discussion

Availability

Declared In

Instance Methods

actionsForTarget:forControlEvent:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

addTarget:action:forControlEvents:

Parameters

Discussion

Availability

See Also

Related Sample Code

Declared In

allControlEvents

Return Value

Availability

See Also

Declared In

allTargets

Return Value

Availability

See Also

Declared In

beginTrackingWithTouch:withEvent: