Contents

UIControl

The base class for controls, which are visual elements that convey a specific action or intention in response to user interactions.

Declaration

@MainActor class UIControl

Mentioned in

Overview

Controls implement elements such as buttons and sliders, which your app can use to facilitate navigation, gather user input, or manipulate content. Controls use the target-action mechanism to report user interactions to your app.

[Image]

You don’t create instances of this class directly. The UIControl class is a subclassing point that you extend to implement custom controls. You can also subclass existing control classes to extend or modify their behaviors. For example, you might override the methods of this class to track touch events yourself or to determine when the state of the control changes.

A control’s state determines its appearance and its ability to support user interactions. Controls can be in one of several states, which the UIControl.State type defines. You can change the state of a control programmatically according to your app’s needs. For example, you might disable a control to prevent the user from interacting with it. User interactions can also change the state of a control.

Respond to user interaction

The target-action mechanism simplifies the code that you write to use controls in your app. Instead of writing code to track touch events, you write action methods to respond to control-specific events. For example, you might write an action method that responds to changes in the value of a slider. The control handles all the work of tracking incoming touch events and determining when to call your methods.

When adding an action method to a control, you specify both the action method and an object that defines that method to the addTarget(_:action:for:) method. (You can also configure the target and action of a control in Interface Builder.) The target object can be any object, but it’s typically the view controller’s root view that contains the control. If you specify nil for the target object, the control searches the responder chain for an object that defines the specified action method.

The signature of an action method takes one of three forms. The sender parameter corresponds to the control that calls the action method, and the event parameter corresponds to the UIEvent object that triggered the control-related event.

The system calls action methods when the user interacts with the control in specific ways. The UIControl.Event type defines the types of user interactions that a control can report and those interactions mostly correlate to specific touch events within the control. When configuring a control, you must specify which events trigger the calling of your method. For a button control, you might use the touchDown or touchUpInside event to trigger calls to your action method. For a slider, you might care only about changes to the slider’s value, so you might choose to attach your action method to valueChanged events.

When a control-specific event occurs, the control calls any associated action methods immediately. The current UIApplication object dispatches action methods and finds an appropriate object to handle the message, following the responder chain, if necessary. For more information about responders and the responder chain, see Event Handling Guide for UIKit Apps.

Configure control attributes in Interface Builder

The following table lists the attributes for instances of the UIControl class.

Attribute

Description

Alignment

The horizontal and vertical alignment of a control’s content. For controls that contain text or images, such as buttons and text fields, use these attributes to configure the position of that content within the control’s bounds. [Image] These alignment options apply to the content of a control and not to the control itself. For information about how to align controls with respect to other controls and views, see TP40010853.

Content

The initial state of the control. Use the checkboxes to configure whether the control is in an enabled, selected, or highlighted state initially.

Support localization

Because UIControl is an abstract class, you don’t internationalize it specifically. However, you do internationalize the content of subclasses like UIButton. For information about internationalizing a specific control, see the reference for that control.

Make controls accessible

Controls are accessible by default. To be useful, an accessible user interface element must provide accurate and helpful information about its screen position, name, behavior, value, and type. This is the information VoiceOver speaks to users. Users who are blind or have low vision can rely on VoiceOver to help them use their devices.

Controls support the following accessibility attributes:

  • Label. A short, localized word or phrase that succinctly describes the control or view, but doesn’t identify the element’s type. Examples are Add and Play.

  • Traits. A combination of one or more individual traits, each of which describes a single aspect of an element’s state, behavior, or usage. For example, you might use a combination of the Keyboard Key and the Selected traits to describe an element that behaves like a keyboard key and that’s in a selected state.

  • Hint. A brief, localized phrase that describes the results of an action on an element. Examples are Adds a title and Opens the shopping list.

  • Frame. The frame of the element in screen coordinates, which the CGRect structure specifies for an element’s screen location and size.

  • Value. The current value of an element when the label doesn’t represent the value. For example, the label for a slider might be Speed, but its current value might be 50%.

The UIControl class provides default content for the value and frame attributes. Many controls automatically enable additional specific traits as well. You can configure other accessibility attributes programmatically or with the Identity inspector in Interface Builder.

For more information about accessibility attributes, see Accessibility Programming Guide for iOS.

Subclassing notes

Subclassing UIControl gives you access to the built-in target-action mechanism and simplified event-handling support. You can subclass existing controls and modify their behavior in one of two ways:

  • Override the sendAction(_:to:for:) method of an existing subclass to observe or modify the dispatching of action methods to the control’s associated targets. You might use this method to modify the dispatch behavior for the specified object, selector, or event.

  • Override the beginTracking(_:with:), continueTracking(_:with:), endTracking(_:with:), and cancelTracking(with:) methods to track touch events occurring in the control. You can use the tracking information to perform additional actions. Always use these methods to track touch events instead of the methods that the UIResponder class defines.

If you subclass UIControl directly, your subclass is responsible for setting up and managing your control’s visual appearance. Use the methods for tracking events to update your control’s state and to send an action when the control’s value changes.

Topics

Creating a control

Managing state

Specifying content alignment

Managing the control’s targets and actions

Triggering actions

Tracking touches and redrawing controls

Managing context menus

Showing tooltips

Inspecting animation status

See Also

Controls