UIAccessibilityElement Class Reference

Inherits from
Conforms to
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
UIAccessibilityElement.h

Overview

The UIAccessibilityElement class encapsulates information about an item that should be accessible to users with disabilities, but that isn’t accessible by default. For example, an icon or text image is not automatically accessible because it does not inherit from UIView (or UIControl). A view that contains such nonview items creates an instance of UIAccessibilityElement to represent each item that needs to be accessible.

The properties of an accessibility element provide information about the element, such as location and current value, to an assistive application. You might need to set an element’s property even if you don’t need to create an instance of UIAccessibilityElement to represent it. For example, if your application includes a button with a custom icon that means “solve,” the button itself is already represented by an accessibility element because it is a subclass of UIButton. However, you need to supply information for the label and hint properties because this information is unique to this button. You can do this in Interface Builder or by setting the properties in the UIAccessibility informal protocol.

Tasks

Creating an Accessibility Element

Accessing the Containing View

Determining Accessibility

Accessing the Attributes of an Accessibility Element

Properties

accessibilityContainer

The view that contains the accessibility element.

@property(nonatomic, assign) id accessibilityContainer
Availability
  • Available in iOS 3.0 and later.
Declared In
UIAccessibilityElement.h

accessibilityFrame

The frame of the accessibility element, in screen coordinates.

@property(nonatomic, assign) CGRect accessibilityFrame
Discussion

When you create an accessibility element to represent an element in your application, you must set this property to the CGRect structure that specifies the object’s screen location and size. (Objects that inherit from UIView include this information by default.)

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

accessibilityHint

A string that briefly describes the result of performing an action on the accessibility element.

@property(nonatomic, retain) NSString *accessibilityHint
Discussion

The hint is a brief, localized description of the result of performing an action on the element without identifying the element or the action. For example, the hint for a table row that contains an email message might be “Selects the message,” but not “Tap this row to select the message.”

By default, standard UIKit controls and views have system-provided hints. If you provide a custom control or view, however, you need to set this property appropriately so that assistive applications can supply accurate information to users with disabilities.

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

accessibilityLabel

A string that succinctly identifies the accessibility element.

@property(nonatomic, retain) NSString *accessibilityLabel
Discussion

The label is a very short, localized string that identifies the accessibility element, but does not include the type of the control or view. For example, the label for a Save button is “Save,” not “Save button.”

By default, standard UIKit controls and views have labels that derive from their titles. If you provide a custom control or view, however, you need to set this property appropriately so that assistive applications can supply accurate information to users with disabilities.

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

accessibilityTraits

The combination of traits that best characterize the accessibility element.

@property(nonatomic, assign) UIAccessibilityTraits accessibilityTraits
Discussion

A trait describes a single aspect of an element’s behavior, state, or usage. Several traits are combined in this property (using an OR operation) to give a complete picture of the element to an assistive application. See “Accessibility Traits” in UIAccessibility Protocol Reference for a complete list of traits.

UIKit provides an appropriate combination of traits for all standard controls and views. When combining traits for a custom accessibility element, be sure to:

  • Use common sense. Don’t combine traits that characterize the element in mutually exclusive ways, such as combining the button and search-field traits.

  • Combine the traits you select with the superclass’s traits. Specifically, always combine your custom traits with [super accessibilityTraits] in the method you use to set a custom element’s traits.

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

accessibilityValue

A string that represents the current value of the accessibility element.

@property(nonatomic, retain) NSString *accessibilityValue
Discussion

The value is a localized string that contains the current value of an element. For example, the value of a slider might be 9.5 or 35% and the value of a text field is the text it contains.

Use the value property only when an accessibility element can have a value that is not represented by its label. For example, a volume slider’s label might be “Volume,” but its value is the current volume level. In this case, it’s not enough for users to know the identity of the slider, because they also need to know its current value. The label of a Save button, on the other hand, tells users everything they need to know about the control; supplying the word “Save” as a value would be unnecessary and confusing.

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

isAccessibilityElement

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

@property(nonatomic, assign) BOOL isAccessibilityElement
Discussion

The default value for this property is NO. If the receiver is a UIKit control, the default value is YES.

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

Instance Methods

initWithAccessibilityContainer:

Creates and initializes an accessibility element to represent an item in the specified container.

- (id)initWithAccessibilityContainer:(id)container
Parameters
container

The view that contains the item.

Return Value

An accessibility element to represent a non-view item in the container.

Discussion

In general, you do not create accessibility elements for items in your application because standard UIKit controls and views are accessible by default. However, if you have a view that contains nonview items, such as icons or text images, that need to be accessible to users with disabilities, you create accessibility elements to represent them. In this case, the containing view should implement the UIAccessibilityContainer informal protocol and use this method to create an accessibility element to represent each item that should be exposed to an assistive application.

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