Documentation Archive


Accessibility Programming Guide for OS X

Enhancing the Accessibility of Standard AppKit Controls

When it comes to accessibility, AppKit does a lot of the heavy lifting for you. AppKit views and controls adopt the NSAccessibility protocol. This provides appropriate default values and implementations for all the information properties and action methods. The AppKit elements also send the appropriate notifications, based on their expected usage.

The system also attempts to fill in many of the information properties with meaningful default values. For example, an NSButton object’s accessibilityLabel property automatically defaults to the button’s title. This means, in many cases, standard AppKit controls do not require any additional work on your part. They are accessibility-enabled straight out of the box.

However, while the AppKit’s default properties are complete, they are not always as useful as we would like. In some cases, you may need to modify these default values to better represent your app, to provide additional context, or to modify the user’s flow through the app. Typically we do this by modifying the information properties.

You can modify these properties in three ways:

  • Using Interface Builder. When using Interface Builder, the Accessibility Identity settings in the Identity inspector let you modify some of the information properties. Specifically, the Description field lets you set the element’s accessibilityLabel property while the Help field let’s you set its accessibilityHelp property.

  • Assigning programmatically. You can assign a new value to any of the properties in code.

  • Overriding accessor methods. If you subclass the AppKit element, you can override the accessor methods for its information properties. This can be more efficient when working with dynamic controls. Here, you simply return the current state upon request—rather than trying to update the property in response to changes.

Enhancing the Default Behavior

When modifying a control’s default accessibility behaviors, start by focusing on the following:

  • Follow the HIG. Make sure your user interface follows the guidelines listed in the OS X Human Interface Guidelines. Accessibility clients expect your app to behave in certain ways. It is considerably easier to accessibility-enable your app when you follow the guidelines in the HIG.

  • Assign a useful label. Every element that the user can interact with must have a meaningful value set for its accessibilityLabel property. Ideally, this label is a single word that briefly describes the control. Add, Play, Delete, Search, Favorites, and Volume all make ideal labels.

    Do not include the type of control in the label. For example, use Add not Add Button. The control’s accessibilityRoleDescription property already captures the control type.

    Also, to ensure that VocieOver reads the label with the correct inflection, the label should start with a capital letter. Do not put a period at the end. Finally, always localize your control’s label.

  • Modify the role description, if necessary. Accessibility clients use the accessibilityRoleDescription property when describing the control. Most of the time, the default value for the role description works perfectly well; however, you might find a few cases where you can make the control’s intent clearer by replacing the default role description. This is particularly true when you are using a standard control in a nonstandard manner.

  • Use help text to describe the effect. Accessibility clients use the accessibilityHelp property to describe the results of performing an action. Essentially, the help text acts like a tool tip.

    Use help text only when the results are not obvious from the control’s label. Just like the label, strive to make the help text as short as possible. Start with a capital letter. Begin with a verb and omit the subject. For example, use “Plays the song” not “This button plays the song.” Also, do not include a description of the action, gesture, view or control. Finally, always localize your help text.

  • Define links and groups to provide context. Visual users often know that sets of controls go together due to their proximity on screen. However, you must explicitly define these relationships before accessibility clients can use them as well. For example, a view could adopt the NSAccessibilityGroup protocol, indicating that its contents should be treated as a group of controls. Similarly, you can use the accessibilityLinkedUIElements property to define the relationship between a list item and the contents displayed in different pane or window. You can also use the accessibilityTitleUIElement to specify the static text element that acts as this control’s label.

  • Focus users on the important parts of the interface. Use the accessibilityElement property to focus the users on the important parts of the interface. If this property is set to NOfalse, accessibility clients ignore this element, skipping directly to its children (if any). By default, NSView and its subclasses set this value to NOfalse. Users are not typically interested in the views. They want to access the things inside the views. However, if your NSView subclass adopts one of the role-specific accessibility protocols, the system automatically changes the accessibilityElement property’s value to YEStrue.

It’s often useful to observe how VoiceOver treats these properties. For example, when you select a control, VoiceOver reads the label and the role description. If you pause with a UI element selected, VoiceOver provides additional guidance and then reads the help text (if any).