| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UIControl.h |
| Related sample code |
UIControl is the base class for controls: objects such as buttons and sliders that are used to convey user intent to the application. You cannot use UIControl directly to instantiate controls. It instead defines the common interface and behavioral structure for all subclasses of it.
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 specified events occur. (See “The Target-Action Mechanism” for an overview.) It 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 (the latter group of methods are for overriding by subclasses).
The design of the target-action mechanism in the UIKit framework is based on the Multi-Touch event model. In iPhone OS the user’s fingers (or touches) convey intent (instead of mouse clicks and drags), and there can be multiple touches at any moment on a control going in different directions.
The UIControl.h header file declares a large number of control events as constants for a bit mask described in “Control Events”. Some control events specify the behavior of touches in and around the control—various permutations of actions such a finger touching down in a control, dragging into and away from a control, and lifting up from a control. Other control events specify editing phases initiated when a finger touches down in a text field. And yet another control event, UIControlEventValueChanged, is for controls such as sliders, where a value continuously changes based on the manipulation of the control. For any particular action message, you can specify one or more control events as the trigger for sending that message. For example, you could request a certain action message be sent to a certain target when a finger touches down in a control or is dragged into it (UIControlEventTouchDown | UIControlEventTouchDragEnter).
You prepare a control for sending an action message by calling addTarget:action:forControlEvents: for each target-action pair you want to specify. This method builds an internal dispatch table associating each target-action pair with a control event. When a user touches the control in a way that corresponds to one or more specified events, UIControl sends itself sendActionsForControlEvents:. This results in UIControl sending the action to UIApplication in a sendAction:to:from:forEvent: message. UIApplication is the centralized dispatch point for action messages; if a nil target is specified for an action message, the application sends the action to the first responder where it travels up the responder chain until it finds an object willing to handle the action message—that is, object that implements a method corresponding to the action selector. (Event Handling gives an overview of the first responder and the responder chain.)
UIKit allows three different forms of action selector:
- (void)action
- (void)action:(id)sender
- (void)action:(id)sender forEvent:(UIEvent *)event
The sendAction:to:fromSender:forEvent: method of UIApplication pushes two parameters when calling the target. These last two parameters are optional for the application because it's up to the caller (usually a UIControl object) to remove any parameters it added.
You may want to extend a UIControl subclass for two basic 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 “Note” 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:.
– sendAction:to:forEvent:
– sendActionsForControlEvents:
– addTarget:action:forControlEvents:
– removeTarget:action:forControlEvents:
– actionsForTarget:forControlEvent:
– allTargets
– allControlEvents
state property
enabled property
selected property
highlighted property
contentVerticalAlignment property
contentHorizontalAlignment property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The horizontal alignment of content (text or image) within the receiver.
@property(nonatomic) UIControlContentHorizontalAlignment contentHorizontalAlignment
A constant that specifies the alignment of text or image within the receiver. See “Horizontal Content Alignment” for descriptions of valid constants.
The value of this property is a constant that specifies the alignment of text or image within the receiver. The default is UIControlContentHorizontalAlignmentLeft.
UIControl.hThe vertical alignment of content (text or image) within the receiver.
@property(nonatomic) UIControlContentVerticalAlignment contentVerticalAlignment
A constant that specifies the alignment of text or image within the receiver. See “Vertical Content Alignment” for descriptions of valid constants.
This value of this property is a constant that specifies the alignment of text or image within the receiver. The default is UIControlContentVerticalAlignmentTop.
UIControl.hA Boolean value that determines whether the receiver is enabled.
@property(nonatomic, getter=isEnabled) BOOL enabled
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.
UIControl.hA Boolean value that determines whether the receiver is highlighted.
@property(nonatomic, getter=isHighlighted) BOOL highlighted
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 and when there is a touch up.
UIControl.hA Boolean value that determines the receiver’s selected state.
@property(nonatomic, getter=isSelected) BOOL selected
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.
UIControl.hA Boolean value that indicates the state of the receiver. (read-only)
@property(nonatomic, readonly) UIControlState state
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.
UIControl.hA Boolean value that indicates whether a touch is inside the bounds of the receiver. (read-only)
@property(nonatomic, readonly, getter=isTouchInside) BOOL touchInside
YES if a touch is inside the receiver’s bounds; otherwise NO.
The value is YES if a touch is inside the receiver’s bounds; otherwise the value is NO.
UIControl.hA Boolean value that indicates whether the receiver is currently tracking touches related to an event. (read-only)
@property(nonatomic, readonly, getter=isTracking) BOOL tracking
The value is YES if the receiver is tracking touches; otherwiseNO.
UIControl.hReturns the actions that are associated with a target and a particular control event.
- (NSArray *)actionsForTarget:(id)target forControlEvent:(UIControlEvents)controlEvent
The target object—that is, the object to which an action message is sent. If this is nil, all actions associated with the control event are returned.
A single constant of type “Note” that specifies a particular user action on the control; for a list of these constants, see “Control Events.”
An array of selector names as NSString objects or nil if there are no action selectors associated with the control event.
Pass in a selector name to the NSSelectorFromString function to obtain the selector (SEL) value.
UIControl.hAdds 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
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.
A selector identifying an action message. It cannot be NULL.
A bitmask specifying the control events for which the action message is sent. See “Control Events” for bitmask constants.
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.
UIControl.hReturns all control events associated with the receiver.
- (UIControlEvents)allControlEvents
One or more “Note” 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.
UIControl.hReturns all target objects associated with the receiver.
- (NSSet *)allTargets
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).
UIControl.hSent the control when a touch related to the given event enters its bounds.
- (BOOL)beginTrackingWithTouch:(UITouch *)touch withEvent:(UIEvent *)event
A UITouch object that represents a touch on the receiving control during tracking.
An event object encapsulating the information specific to the user event.
YES if the receiver is set to respond continuously or set to respond when a touch is dragged; otherwise NO.
UIControl.hTells the control to cancel tracking related to the given event.
- (void)cancelTrackingWithEvent:(UIEvent *)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.
UIControl.hSent continuously to the control as it tracks a touch related to the given event within its bounds.
- (BOOL)continueTrackingWithTouch:(UITouch *)touch withEvent:(UIEvent *)event
A UITouch object that represents a touch on the receiving control during tracking.
An event object encapsulating the information specific to the user event
YES if mouse tracking should continue; otherwise NO.
UIControl.hSent 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
A UITouch object that represents a touch on the receiving control during tracking.
An event object encapsulating the information specific to the user event.
UIControl.hRemoves 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
The target object—that is, the object to which the action message is sent.
A selector identifying an action message. Pass NULL to remove all action messages paired with target.
A bitmask specifying the control events associated with target and action. See “Control Events” for bitmask constants.
UIControl.hIn 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
A selector identifying an action message. It cannot be NULL.
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.
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.
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.
UIControl.hSends action messages for the given control events.
- (void)sendActionsForControlEvents:(UIControlEvents)controlEvents
A bitmask whose set flags specify the control events for which action messages are sent. See “Control Events” for bitmask constants.
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:.
UIControl.hThe type for the enum constants listed in “Control Events.”
typedef NSUInteger UIControlEvents;
UIControl.hKinds 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
};
UIControlEventTouchDownA touch-down event in the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchDownRepeatA repeated touch-down event in the control; for this event the value of the UITouch tapCount method is greater than one.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchDragInsideAn event where a finger is dragged inside the bounds of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchDragOutsideAn event where a finger is dragged just outside the bounds of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchDragEnterAn event where a finger is dragged into the bounds of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchDragExitAn event where a finger is dragged from within a control to outside its bounds.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchUpInsideA touch-up event in the control where the finger is inside the bounds of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchUpOutsideA touch-up event in the control where the finger is outside the bounds of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventTouchCancelA system event canceling the current touches for the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventValueChangedA touch dragging or otherwise manipulating a control, causing it to emit a series of different values.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventEditingDidBeginA touch initiating an editing session in a UITextField object by entering its bounds.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventEditingChangedA touch making an editing change in a UITextField objet.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventEditingDidEndA touch ending an editing session in a UITextField object by leaving its bounds.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventEditingDidEndOnExitA touch ending an editing session in a UITextField object.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventAllTouchEventsAll touch events.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventAllEditingEventsAll editing touches for UITextField objects.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventApplicationReservedA range of control-event values available for application use.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventSystemReservedA range of control-event values reserved for internal framework use.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlEventAllEventsAll events, including system events.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
The vertical alignment of content (text and images) within a control.
typedef enum {
UIControlContentVerticalAlignmentCenter = 0,
UIControlContentVerticalAlignmentTop = 1,
UIControlContentVerticalAlignmentBottom = 2,
UIControlContentVerticalAlignmentFill = 3,
} UIControlContentVerticalAlignment;
UIControlContentVerticalAlignmentCenterAligns the content vertically in the center of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentVerticalAlignmentTopAligns the content vertically at the top in the control (the default).
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentVerticalAlignmentBottomAligns the content vertically at the bottom in the control
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentVerticalAlignmentFillAligns the content vertically to fill the content rectangle; images may be stretched.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
You use these constants as the value of the contentVerticalAlignment property.
The horizontal alignment of content (text and images) within a control.
typedef enum {
UIControlContentHorizontalAlignmentCenter = 0,
UIControlContentHorizontalAlignmentLeft = 1,
UIControlContentHorizontalAlignmentRight = 2,
UIControlContentHorizontalAlignmentFill = 3,
} UIControlContentHorizontalAlignment;
UIControlContentHorizontalAlignmentCenterAligns the content horizontally in the center of the control.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentHorizontalAlignmentLeftAligns the content horizontally from the left of the control (the default).
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentHorizontalAlignmentRightAligns the content horizontally from the right of the control
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlContentHorizontalAlignmentFillAligns the content horizontally to fill the content rectangles; text may wrap and images may be stretched.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
You use these constants as the value of the contentHorizontalAlignment property.
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
};
UIControlStateNormalThe normal, or default state of a control—that is, enabled but neither selected or highlighted.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlStateHighlightedHighlighted state of a control. A control enters this state when a touch enters and exits during tracking and and when there is a touch up. You can retrieve and set this value through the highlighted property.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlStateDisabledDisabled 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 iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlStateSelectedSelected state of a control. For many controls, this state has no effect on behavior or appearance. But other subclasses (for example, UISwitchControl). You can retrieve and set this value through the selected property.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlStateApplicationAdditional control-state flags available for application use.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UIControlStateReservedControl-state flags reserved for internal framework use.
Available in iPhone OS 2.0 and later.
Declared in UIControl.h.
UITouch.hThe bit-mask type for control-state constants.
typedef NSUInteger UIControlState;
The constants are listed in “Control State.” Use the state property to retrieve the current state bits set for a control.
UIControl.hLast updated: 2009-03-26
