UIAccessibility Protocol Reference

(informal protocol)

Adopted by
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
UIAccessibility.h
UIAccessibilityConstants.h
UIAccessibilityZoom.h

Overview

The UIAccessibility informal protocol provides accessibility information about an application’s user interface elements. Assistive applications, such as VoiceOver, convey this information to users with disabilities to help them use the application.

Standard UIKit controls and views implement the UIAccessibility methods and are therefore accessible to assistive applications by default. This means that if your application uses only standard controls and views, such as UIButton, UISegmentedControl, and UITableView, you need only supply application-specific details when the default values are incomplete. You can do this by setting these values in Interface Builder or by setting the properties in this informal protocol.

The UIAccessibility informal protocol is also implemented by the UIAccessibilityElement class, which represents custom user interface objects. If you create a completely custom UIView subclass, you might need to create an instance of UIAccessibilityElement to represent it. In this case, you would support all the UIAccessibility properties to correctly set and return the accessibility element’s properties.

Tasks

Determining Accessibility

Configuring an Accessibility Element

Properties

accessibilityActivationPoint

The activation point for the accessibility element, in screen coordinates.

@property(nonatomic) CGPoint accessibilityActivationPoint
Discussion

The default value for this property is the midpoint of the accessibility element’s frame, which is given by accessibilityFrame. The activation point for an element is the specific area VoiceOver activates when a user double-taps the element.

The ability to specify an activation point allows an element to present to VoiceOver different points in different circumstances without changing how the element presents itself. For example, the standard activation point for a Home screen app icon is the midpoint of the icon. But when the user is rearranging icons on the Home screen, the activation point changes to the midpoint of the remove control (that is, to the circled X in the upper-left corner of the icon).

You can also use this property to ensure that the activation point for a small element remains accurate even if you present a larger version of the element to VoiceOver.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIAccessibility.h

accessibilityElementsHidden

A Boolean value indicating whether the accessibility elements contained within this accessibility element are hidden.

@property(nonatomic) BOOL accessibilityElementsHidden
Discussion

The default value for this property is NO. You might use this property to hide views that are covered by the arrival of a new view. In this case, the hidden views might remain visible onscreen, but they are not the focus of the user’s actions.

You might also use this property to hide a transient view that VoiceOver users don’t need to notice. For example, VoiceOver doesn’t need to describe the translucent view that appears when users adjust the volume on their devices, because the aural feedback of this action is sufficient.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIAccessibility.h

accessibilityFrame

The frame of the accessibility element, in screen coordinates.

@property(nonatomic) CGRect accessibilityFrame
Discussion

The default value for this property is CGRectZero unless the receiver is a UIView object or is a subclass of UIView, in which case the value is the frame of the view.

You must set this property for an accessibility element that represents an object that is not a subclass of UIView, because the screen coordinates of such an object are not already known. (You do not have to set this property for an accessibility element that represents a subclass of UIView, because such an object’s screen coordinates are already known.)

Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibility.h

accessibilityHint

A brief description of the result of performing an action on the accessibility element, in a localized string.

@property(nonatomic, copy) NSString *accessibilityHint
Discussion

The default value for this property is nil unless the receiver is a UIKit control, in which case the value is a system-provided hint based on the type of control.

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label. For example, if you provide an Add button in your application, the button’s accessibility label helps users understand that tapping the button adds values in the application. If, on the other hand, your application allows users to play a song by tapping its title in a list of song titles, the accessibility label for the list row does not tell users this. To help an assistive application provide this information to users with disabilities, an appropriate hint for the list row would be “Plays the song.”

Follow these guidelines to create a hint for an accessibility element:

  • The hint should be a very brief phrase that begins with a verb that names the results of the action, such as “Plays the song” or “Purchases the item.”

    Avoid beginning the phrase with the imperative form of a verb, because this can make the hint sound like a command. For example, do not create a hint such as “Play the song” or “Purchase the item.”

  • Don’t repeat the action type in the hint. For example, do not create hints such as “Tap to play the song” or “Tapping plays the song.”

  • Don’t repeat the control or view type in the hint. For example, do not create hints such as “Plays the song in the row” or “Button that adds a contact name.”

Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibility.h

accessibilityLabel

A succinct label that identifies the accessibility element, in a localized string.

@property(nonatomic, copy) NSString *accessibilityLabel
Discussion

The default value for this property is nil unless the receiver is a UIKit control, in which case the value is a label derived from the control’s title.

If you implement a custom control or view, or if you display a custom icon on a UIKit control, you should set this property to make sure your accessibility elements have appropriate labels. If an accessibility element does not display a descriptive label, set this property to supply a short, localized label that succinctly identifies the element. For example, a “Play music” button might display an icon that shows sighted users what it does. To be accessible, however, the button should have the accessibility label “Play” or “Play music” so that an assistive application can provide this information to users with disabilities. Note, however, that the label should never include the control type (such as “button”) because this information is contained in the traits associated with the accessibility element.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibility.h

accessibilityLanguage

The language in which to speak the accessibility element's label, value, and hint.

@property(nonatomic, retain) NSString *accessibilityLanguage
Discussion

The default value for this property is nil. If no language is set, the user’s current language setting is used.

If you need to set this property, be sure to use a language ID tag that follows the format defined in the BCP 47 specification. A draft of this specification is available at http://www.rfc-editor.org/.

Availability
  • Available in iOS 4.0 and later.
Declared In
UIAccessibility.h

accessibilityPath

The path of the element, in screen coordinates.

@property (nonatomic, copy) UIBezierPath *accessibilityPath
Discussion

The default value of this property is nil. If no path is set, the accessibility frame rectangle is used to highlight the element.

When you specify a value for this property, the assistive technology uses the path object you specify (instead of the accessibility frame) to highlight the element.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIAccessibility.h

accessibilityTraits

The combination of accessibility traits that best characterize the accessibility element.

@property(nonatomic) UIAccessibilityTraits accessibilityTraits
Discussion

The default value for this property is UIAccessibilityTraitNone unless the receiver is a UIKit control, in which case the value is the standard set of traits associated with the control.

If you implement a custom control or view, you need to select all the accessibility traits that best characterize the object and combine them with its superclass’s traits (in other words, with super.accessibilityTraits) by performing an OR operation. See “Accessibility Traits” for a complete list of traits.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibility.h

accessibilityValue

The value of the accessibility element, in a localized string.

@property(nonatomic, copy) NSString *accessibilityValue
Discussion

The default value for this property is nil unless the receiver is a UIKit control, in which case value of the property represents the value of the control, when it differs from the label.

When an accessibility element has a static label, and a dynamic value, you should set this property to return the value. For example, although an accessibility element that represents a text field might have the label “Message,” its value is the text currently inside the text field.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
UIAccessibility.h

accessibilityViewIsModal

A Boolean value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver.

@property(nonatomic) BOOL accessibilityViewIsModal
Discussion

The default value for this property is NO. When the value of this property is YES, VoiceOver ignores the elements within the sibling views of the receiving view.

For example, in a window that contains sibling views A and B, setting accessibilityViewIsModal to YES on view B causes VoiceOver to ignore the elements in the view A. On the other hand, if view B contains a child view C and you set accessibilityViewIsModal to YES on view C, VoiceOver does not ignore the elements in view A.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIAccessibility.h

isAccessibilityElement

A Boolean value indicating whether the receiver is an accessibility element that an assistive application can access.

@property(nonatomic) BOOL isAccessibilityElement
Discussion

The default value for this property is NO unless the receiver is a standard UIKit control, in which case the value is YES.

Assistive applications can get only information about objects that are represented by accessibility elements. Therefore, if you implement a custom control or view that should be accessible to users with disabilities, you should set this property to YES. The only exception to this practice is a view that merely serves as a container for other items that should be accessible. Such a view should implement the UIAccessibilityContainer protocol and set this property to NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibility.h

shouldGroupAccessibilityChildren

A Boolean value indicating whether VoiceOver should group together the elements that are children of the receiver, regardless of their positions on the screen.

@property(nonatomic) BOOL shouldGroupAccessibilityChildren
Discussion

The default value for this property is NO.

For example, consider an app that shows items in vertical columns. Normally, VoiceOver would navigate through these items in horizontal rows. Setting the value of this property to YES on the parent view of the items in the vertical columns causes VoiceOver to respect the app’s grouping and navigate them correctly.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIAccessibility.h

Constants

UIAccessibilityTraits

A mask that contains the OR combination of the accessibility traits that best characterize an accessibility element.

typedef uint64_t UIAccessibilityTraits;
Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibilityConstants.h

Accessibility Traits

Accessibility traits that tell an assistive application how an accessibility element behaves or should be treated.

UIAccessibilityTraits UIAccessibilityTraitNone;
UIAccessibilityTraits UIAccessibilityTraitButton;
UIAccessibilityTraits UIAccessibilityTraitLink;
UIAccessibilityTraits UIAccessibilityTraitSearchField;
UIAccessibilityTraits UIAccessibilityTraitImage;
UIAccessibilityTraits UIAccessibilityTraitSelected;
UIAccessibilityTraits UIAccessibilityTraitPlaysSound;
UIAccessibilityTraits UIAccessibilityTraitKeyboardKey;
UIAccessibilityTraits UIAccessibilityTraitStaticText;
UIAccessibilityTraits UIAccessibilityTraitSummaryElement;
UIAccessibilityTraits UIAccessibilityTraitNotEnabled;
UIAccessibilityTraits UIAccessibilityTraitUpdatesFrequently;
UIAccessibilityTraits UIAccessibilityTraitStartsMediaSession;
UIAccessibilityTraits UIAccessibilityTraitAdjustable;
UIAccessibilityTraits UIAccessibilityTraitAllowsDirectInteraction;
UIAccessibilityTraits UIAccessibilityTraitCausesPageTurn;
UIAccessibilityTraits UIAccessibilityTraitHeader;
Constants
UIAccessibilityTraitNone

The accessibility element has no traits.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitButton

The accessibility element should be treated as a button.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitLink

The accessibility element should be treated as a link.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitSearchField

The accessibility element should be treated as a search field.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitImage

The accessibility element should be treated as an image.

This trait can be combined with the button or link traits.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitSelected

The accessibility element is currently selected.

You can use this trait to characterize an accessibility element that represents, for example, a selected table row or a selected segment in a segmented control.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitPlaysSound

The accessibility element plays its own sound when activated.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitKeyboardKey

The accessibility element behaves as a keyboard key.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitStaticText

The accessibility element should be treated as static text that cannot change.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitSummaryElement

The accessibility element provides summary information when the application starts.

You can use this trait to characterize an accessibility element that provides a summary of current conditions, settings, or state, such as the current temperature in the Weather application.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitNotEnabled

The accessibility element is not enabled and does not respond to user interaction.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitUpdatesFrequently

The accessibility element frequently updates its label or value.

You can use this trait to characterize an accessibility element that updates its label or value too often to send update notifications. Include this trait when you want an assistive application to avoid handling continual notifications and, instead, poll for changes when it needs updated information. For example, you might use this trait to characterize the readout of a stopwatch.

Available in iOS 3.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitStartsMediaSession

The accessibility element starts a media session when it is activated.

You can use this trait to silence the audio output of an assistive technology, such as VoiceOver, during a media session that should not be interrupted. For example, you might use this trait to silence VoiceOver speech while the user is recording audio.

Available in iOS 4.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitAdjustable

The accessibility element allows continuous adjustment through a range of values.

You can use this trait to characterize an accessibility element that users can adjust in a continuous manner, such as a slider or a picker view. If you specify this trait on an accessibility element, you must also implement the accessibilityIncrement and accessibilityDecrement methods in the UIAccessibilityAction protocol.

Available in iOS 4.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitAllowsDirectInteraction

The accessibility element allows direct touch interaction for VoiceOver users.

You can use this trait to characterize an accessibility element that represents an object that users interact with directly, such as a view that represents a piano keyboard.

Available in iOS 5.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitCausesPageTurn

The accessibility element should cause an automatic page turn when VoiceOver finishes reading the text within it.

You can use this trait to characterize an accessibility element that represents a page of content within a set of pages, such as view that represents a page in a book. When VoiceOver finishes reading the content in the current page, it calls accessibilityScroll with UIAccessibilityScrollDirectionNext to scroll to the next content page. If VoiceOver detects that the new content does not differ from the previous content, it stops scrolling.

Available in iOS 5.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityTraitHeader

The accessibility element is a header that divides content into sections, such as the title of a navigation bar.

Available in iOS 6.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityZoomType

The types of system Zoom that can be in effect.

typedef enum {
   UIAccessibilityZoomTypeInsertionPoint,
} UIAccessibilityZoomType;
Constants
UIAccessibilityZoomTypeInsertionPoint

The system zoom type is the text insertion point.

Available in iOS 5.0 and later.

Declared in UIAccessibilityZoom.h.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIAccessibilityZoom.h

UIAccessibilityNotifications

A notification that an accessible application can send.

typedef uint32_t UIAccessibilityNotifications;
Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibilityConstants.h

Notification Dictionary Keys

Keys used in the userInfo parameter dictionary of notifications.

NSString *const UIAccessibilityAnnouncementKeyStringValue;
NSString *const UIAccessibilityAnnouncementKeyWasSuccessful;
Constants
UIAccessibilityAnnouncementKeyStringValue

The text of the announcement that finished.

Available in iOS 6.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilityAnnouncementKeyWasSuccessful

Indicates whether the announcement was successfully made.

The value of this key is an NSNumber object that you should interpret as a Boolean value.

Available in iOS 6.0 and later.

Declared in UIAccessibilityConstants.h.

Speech Attributes for Attributed Strings

Attributes that you can apply to text in an attributed string to modify how that text is pronounced.

NSString *const UIAccessibilitySpeechAttributePunctuation;
NSString *const UIAccessibilitySpeechAttributeLanguage;
NSString *const UIAccessibilitySpeechAttributePitch;
Constants
UIAccessibilitySpeechAttributePunctuation

The value of this key is an NSNumber object that you should interpret as a Boolean value. When the value is YES, all punctuation in the text is spoken. You might use this for code or other text where the punctuation is relevant.

Available in iOS 7.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilitySpeechAttributeLanguage

The value of this key is an NSString object containing a BCP-47 language code. When applied to text in a string, the rules for the specified language govern how that string is pronounced.

Available in iOS 7.0 and later.

Declared in UIAccessibilityConstants.h.

UIAccessibilitySpeechAttributePitch

The value of this key is an NSNumber object containing a floating-point value in the range 0.0 to 2.0. The value indicates whether the text should be specified spoken with a higher or lower pitch than the default. The default value for this attribute is 1.0, which indicates a normal pitch. Values between 0.0 and 1.0 result in a lower pitch and values between 1.0 and 2.0 result in a higher pitch.

Available in iOS 7.0 and later.

Declared in UIAccessibilityConstants.h.

Notifications

There are two types of accessibility notifications: those which your app can post, and those which your app can observe. The observable accessibility notifications are posted by UIKit when something in the app’s environment changes, such as when an accessibility setting is toggled, or when the layout of a screen changes. You post accessibility notifications with UIAccessibilityPostNotification and observe with the default notification center.

UIAccessibilityAnnouncementNotification

Posted by an application when an announcement needs to be conveyed to the assistive technology. This notification includes a parameter, which is an NSString object that contains the announcement. An assistive technology outputs the announcement string contained in the parameter.

Use this notification to provide accessibility information about events that do not update the application user interface (UI), or that update the UI only briefly.

Availability
Declared In
UIAccessibilityConstants.h

UIAccessibilityAnnouncementDidFinishNotification

Posted by UIKit when the system has finished reading an announcement. The parameter is a dictionary with two keys, UIAccessibilityAnnouncementKeyStringValue and UIAccessibilityAnnouncementKeyWasSuccessful.
Availability
Declared In
UIAccessibilityConstants.h

UIAccessibilityClosedCaptioningStatusDidChangeNotification

Posted by UIKit when the setting for closed captioning has changed. This notification does not include a parameter.
Availability
Declared In
UIAccessibility.h

UIAccessibilityGuidedAccessStatusDidChangeNotification

Posted by UIKit when the setting for Guided Access has changed. This notification does not include a parameter.

You can also use the UIAccessibilityIsGuidedAccessEnabled function to determine whether guided access is currently enabled.

Availability
Declared In
UIAccessibility.h

UIAccessibilityInvertColorsStatusDidChangeNotification

Posted by UIKit when the setting for inverted colors has changed. This notification does not include a parameter.

You can also use the UIAccessibilityIsInvertColorsEnabled function to determine whether colors are currently inverted.

Availability
Declared In
UIAccessibility.h

UIAccessibilityLayoutChangedNotification

Posted by an application when the layout of a screen changes, such as when an element appears or disappears. This notification includes a parameter, which is either an NSString object that VoiceOver speaks or an accessibility element that VoiceOver moves to.
Availability
Declared In
UIAccessibilityConstants.h

UIAccessibilityMonoAudioStatusDidChangeNotification

Posted by UIKit when system audio changes from stereo to mono. This notification does not include a parameter.
Availability
Declared In
UIAccessibility.h

UIAccessibilityPageScrolledNotification

Posted by an application when a scroll action has completed and accessibilityScroll: has been called. This notification includes a parameter, which is an NSString object that contains a description of the new scroll position. An assistive technology outputs the description string contained in the parameter.

You can use this notification to provide custom information about the contents of the screen after a user performs a VoiceOver scroll gesture. For example, a tab-based application might provide a string such as “Tab 3 of 5,” or an application that displays information in pages might provide a string such as “Page 19 of 27.”

When an assistive technology repeatedly receives the same scroll position string, it indicates to users that a border or boundary has been reached.

Availability
Declared In
UIAccessibilityConstants.h

UIAccessibilityScreenChangedNotification

Posted by an application when a new view appears that comprises a major portion of the screen. This notification includes a parameter, which is either an NSString object that VoiceOver speaks or an accessibility element that VoiceOver moves to.
Availability
Declared In
UIAccessibilityConstants.h

UIAccessibilityVoiceOverStatusChanged

Posted by UIKit when VoiceOver starts or stops. This notification does not include a parameter.

You can use this notification to customize your application’s user interface (UI) for VoiceOver users. For example, if you display a UI element that briefly overlays other parts of your UI, you can make the display persistent for VoiceOver users, but allow it to disappear as designed for users who are not using VoiceOver. You can also use the UIAccessibilityIsVoiceOverRunning function to determine whether VoiceOver is currently running.

Availability
Declared In
UIAccessibility.h