Skip to content
This repository was archived by the owner on Jul 30, 2020. It is now read-only.

Accessibility Tips

Jump to bottom
ferrous26 edited this page Apr 21, 2012 · 5 revisions

This document includes tips for customizing accessibility in your own applications. The goal is to inform you of pitfalls that are not mentioned in Apple's documentation. It also includes notes on how to avoid making decsions that will make an application incompatible with AXElements.

Guidelines

  • Do not pluralize (sub)role

When implementing custom accessibility roles, you should never use a pluralized name for the role. A role that is already pluralized will break search in AXElements.

  • Attributes/parameterized attributes/actions should all start with AX

This is an assumption that AXElements makes in order to keep code simpler. This assumption holds for every app that I have checked out with only one exception.

Adding/Changing Attributes/Actions

The NSAccessibility protocol is the way that an application can add new accessibility information to itself.

Also, the NSUserInterfaceItemIdentification protocol is very useful for quickly adding an identifying string to an accessibility object. See the Other Resources section of this page for a link to some relevant WWDC videos.

New Attributes

Either use accessibilitySetOverrideValue:forAttribute: to set a single attribute, or implement/override both accessibilityAttributeNames and accessibilityAttributeValue.

New Actions

Similarly, use accessibilityActionNames and accessibilityPerformAction to add new actions.

Where To Implement The Methods

The difficulty in adding attributes lies in finding out where you need to add the accessibility methods. Often, the class that implements accessibility is the class that draws the user interface element. For example, the accessibility information for a button is implemented on the button cell and not the button itself.

Writability

When adding a writable attribute, you will also need to implement/override accessibilityIsAttributeSettable: and accessibilitySetValue:forAttribute:

NOTE: Don't forget to call super when overriding.

Existing Definitions

When implementing custom behaviour, you should try and use pseudo classes that have already been defined by Apple; the same goes for attributes, parameterized attributes, and other features that have already been defined. Apple maintains the documentation for all their definitions here. The documentation is fairly detailed now (moreso than before), but still misses a few things.

Other Resources

Programatically Enabling/Disabling Accessibility

If you do not want to go to the system preferences for each machine that needs to enable/disable accessibility then there are two ways to programatically enable/disable accessibility.

  1. There is a file, /var/db/.AccessibilityAPIEnabled that the system uses as a global flag. If it exists then AXAPI is enabled, if it is removed then AXAPI is disabled. You will need root privileges to add/remove the file.

  2. Use the AXMakeProcessTrusted() function. This will only make a specific application accessibility enabled. If you run AXElements outside of an application then you will need to make MacRuby trusted. This API is not the preferred way to grant permissions because there is no way to undo the permission granting, even if you disable AXAPI globally.

Clone this wiki locally