(informal protocol)
| Adopted by | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Companion guide | |
| Declared in | UIAccessibility.h UIAccessibilityConstants.h |
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 implementing the appropriate methods 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 implement all the UIAccessibility methods to correctly set and return the accessibility element’s properties.
– isAccessibilityElement required method
– setIsAccessibilityElement: required method
– accessibilityLabel required method
– setAccessibilityLabel: required method
– accessibilityHint required method
– setAccessibilityHint: required method
– accessibilityValue required method
– setAccessibilityValue: required method
– accessibilityTraits required method
– setAccessibilityTraits: required method
– accessibilityFrame required method
– setAccessibilityFrame: required method
Returns the frame of the accessibility element. (required)
- (CGRect)accessibilityFrame
The frame of the accessibility element in screen coordinates. This method returns CGRectZero by default unless the receiver is a UIView or subclass of UIView, in which case it returns the frame of the view in screen coordinates.
UIAccessibility.hReturns a hint that describes the result of performing an action on the accessibility element. (required)
- (NSString *)accessibilityHint
A brief description of the result of performing an action on the accessibility element, as a localized string. This method returns nil by default unless the receiver is a UIKit control, in which case it returns 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.
UIAccessibility.hReturns a label that identifies the accessibility element. (required)
- (NSString *)accessibilityLabel
A succinct label that identifies the accessibility element, in a localized string. This method returns nil by default unless the receiver is a UIKit control, in which case it returns a label derived from the control’s title.
UIAccessibility.hReturns the combination of accessibility traits that characterize the accessibility element. (required)
- (UIAccessibilityTraits)accessibilityTraits
The accessibility traits that best characterize the accessibility element. This method returns UIAccessibilityTraitNone by default unless the receiver is a UIKit control, in which case it returns the standard set of traits associated with the control.
UIAccessibility.hReturns the value of the accessibility element. (required)
- (NSString *)accessibilityValue
The value of the accessibility element, when it differs from the label.
When an accessibility element has a static label, but a dynamic value, you should implement this method 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.
UIAccessibility.hReturns a Boolean value indicating whether the receiver is an accessibility element that an assistive application can access. (required)
- (BOOL)isAccessibilityElement
YES if the receiver is an accessibility element; otherwise, NO. This method returns NO by default unless the receiver is a standard UIKit control, in which case it returns YES.
Assistive applications can only get 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, your implementation of this method should return YES. The only exception to this 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 return NO in this method.
UIAccessibility.hSets the frame of the accessibility element to the specified rectangle. (required)
- (void)setAccessibilityFrame:(CGRect)frame
The frame of the accessibility element, in screen coordinates.
You must implement this method 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 implement this method for an accessibility element that represents a subclass of UIView because such an object’s screen coordinates are already known.)
UIAccessibility.hSets an accessibility element’s hint to the specified description. (required)
- (void)setAccessibilityHint:(NSString *)hint
A localized string that briefly describes the result of performing an action on the accessibility element.
A hint briefly describes the result of performing an action on a view or control, when that result is not obvious. 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 plural verb that names the results of the action, such as “Plays the song” or “Purchases the item.”
Avoid beginning the phrase with a singular 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.”
UIAccessibility.hSets an accessibility element’s label to the specified value. (required)
- (void)setAccessibilityLabel:(NSString *)label
The localized string that succinctly identifies the accessibility element.
If you implement a custom control or view, or if you display a custom icon on a UIKit control, you should implement this method to make sure your accessibility elements have appropriate labels. If an accessibility element does not display a descriptive label, use this method 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.
UIAccessibility.hSets an accessibility element’s traits to the specified combination of traits. (required)
- (void)setAccessibilityTraits:(UIAccessibilityTraits)traits
The OR combination of all accessibility traits that best characterize the accessibility element. See “Accessibility Traits” for a complete list of traits.
If you implement a custom control or view, you need to select all the accessibility traits that best characterize the object and OR them together with its superclass’s traits (in other words, with the results of [super accessibilityTraits]).
UIAccessibility.hSets the value of the accessibility element to the specified value. (required)
- (void)setAccessibilityValue:(NSString *)value
The value of the accessibility element, in a localized string.
When an accessibility element has a value that is not expressed in its label, it should provide an accessibility value. For example, a volume slider might have the label “Volume,” but its value could be “9” or “90%.”
UIAccessibility.hSets the receiver’s accessibility element status to the specified value. (required)
- (void)setIsAccessibilityElement:(BOOL)isElement
If YES, the receiver should be considered an accessibility element; if NO, the receiver should not be considered an accessibility element.
If you implement a custom control or view, you should implement this method to make sure you provide accurate accessibility information about the control or view.
UIAccessibility.hA mask that contains the OR combination of the accessibility traits that best characterize an accessibility element.
typedef uint64_t UIAccessibilityTraits;
UIAccessibilityConstants.hValues that encapsulate individual accessibility traits that inform 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;
UIAccessibilityTraitNoneThe accessibility element has no traits.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitButtonThe accessibility element should be treated as a button.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitLinkThe accessibility element should be treated as a link.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitSearchFieldThe accessibility element should be treated as a search field.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitImageThe accessibility element should be treated as an image.
This trait can be combined with the button or link traits.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitSelectedThe 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 iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitPlaysSoundThe accessibility element plays its own sound when activated.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitKeyboardKeyThe accessibility element behaves as a keyboard key.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitStaticTextThe accessibility element should be treated as static text that cannot change.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitSummaryElementThe 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 iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitNotEnabledThe accessibility element is not enabled and does not respond to user interaction.
Available in iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
UIAccessibilityTraitUpdatesFrequentlyThe 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. Including this trait allows 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 iPhone OS 3.0 and later.
Declared in UIAccessibilityConstants.h.
A notification that an accessible application can send.
typedef uint32_t UIAccessibilityNotifications;
UIAccessibilityConstants.hPosted by an application when a new view appears that comprises a major portion of the screen. This notification does not include an argument.
UIAccessibilityConstants.hPosted by an application when the layout of a screen changes, such as when an element appears or disappears. This notification does not include an argument.
UIAccessibilityConstants.hLast updated: 2009-07-14
