View source for Accessibility/Mac/ContributorGuide

= Mac Accessibility Contributor's Guide =

== Code Style ==

Our code style is based on Google's Objective C Style Guide

== Architecture and Design ==

The goal of this design is to allow us to provide customized interfaces for different accessibility roles in a concise and readable way that does not compromise on flexibility and possible future OSX API changes.

=== Protocols ===

==== mozAccessible Protocol ====
This consists of the API necessary to talk to platform accessibility (<code>accessibilityAttributeValue</code>, etc.) and widget code (<code>representedView</code>, etc.)

==== mozAccessibleInner Protocol ====
This inner protocol's API is a mapping to Apple's attributes and actions. It allows us to have simple getter and setter methods for each attribute and a method for performing each action. All methods are optional, so an implementing object gets to choose which subset of these methods it supports. This gets reflected in what is returned to platform in  <code>accessibilityAttributeNames</code> and friends. An instance can also programatically block a method if it is defined and it will be excluded from the mapping.

=== Classes ===

==== mozAccessibleBase ====

The abstract base class for all our platform accessibles. This class:
* Implements the platform and widget API defined in the <code>mozAccessible</code> protocol. The platform API it implements should be considered "final" (there is no way in Objective C to enforce this).
* Forwards platform methods to the mapped inner protocol's methods.
* Filters ignored accessibles and ensures they are not exposed to the platform.

A subclass should be able to implement a handful of inner protocol getters and have a well-behaved platform accessible. An example of that is <code>mozColumnAccessible</code>.

==== mozAccessible ====

The base class for all accessibles that wrap a Gecko accessible. This class:
* Maps gecko roles to platform roles, subroles, and role descriptions.
* Caches and utilizes gecko states.
* Forwards gecko accessible events to platform notifications.
* Provides parent and children getters via gecko's hierarchy.
* Provides a base set of attributes and actions that most gecko accessibles support.

==== mozAccessible subclasses ====

Subclasses of mozAccessible are mainly gecko role-based and typically provide additional attributes that the type uses. For example a mathml subclass might provide mathml related attributes via implemented inner protocol methods (eg. <code>mathRootRadicand</code>). An accessible that backs a slider might implement special actions via the inner protocol, like <code>performIncrement</code>.