Accessibility/AJAX:WAI ARIA Live Region Library

From MozillaWiki
Jump to: navigation, search

Purpose

To develop an expert system recommending actions an AT might take in response to a queue of live region changes over time.

Proposed API

Here are some rough ideas for a live region library, which would manage the queue. For the moment, I'd like to assume the library is written in Python for the sake of syntax.

Processing a change

def processEvent(node, event_type):
  '''
  Processes a live region event by adding a recommendation to the queue for later use by the AT.

  @param node: A hashable object representing the live region
  @type node: hashable
  @param event_type: Constant representing the kind of change: node addition, node removal
  or text insert/delete
  @type event_type: integer
  '''

Getting a recommendation

def getNextRecommendation():
  '''
  Retrieves the next recommendation from the queue.

  @return: Recommendation of how to announce a live region change
  @rtype: Recommendation
  '''
def clearQueue():
  '''
  Clears the queue of recommendations.
  '''

Accessibility callbacks

Allows the AT to register methods the library should call to get information about accessibles. These callbacks allow the library to be cross-platform.

def registerGetParent(func):
  '''
  Registers a callback for getting the parent of a given node.
  
  @param func: Function that returns a parent node of the given node.
  @type func: callable
  '''
  • registerGetControlsRelation(func)
  • registerGetLabelledByRelation(func)
  • registerGetDescribedByRelation(func)
  • registerGetLiveRegionAttrsProperties()
  • What else?

Rude change callbacks

Original spec by Aaron. But don't the rude changes get pushed to the library via the processEvent method anyways? Couldn't the return value on that method indicate whether getNextRecommendation should be called immediately or not?

  • registerPushListener() // Register a listener so that if rude changes occur, the library can call back in and push a region
  • setLastPushSucccess(boolean) // Was the last live region push successfully presented?

Settings

def setGlobalSettings(settings):
  '''
  Updates settings for all live regions, either on the current page or across pages.

  @param settings: Name/value setting pairs. Either all settings or a subset to update.
  @type settings: dictionary
  '''
def setNodeSettings(node, settings):
  '''
  Updates settings for a particular live region. Any settings not defined here fall
  back to using the global equivalents. Setting any particular setting name to value
  None removes that setting from this node, and forces it to use the global value for
  the setting.

  @param node: A hashable object representing the live region
  @type node: hashable
  @param settings: Name/value setting pairs. Either all settings or a subset to update.
  @type settings: dictionary
  '''
def clearNodeSettings(node):
  '''
  Forces the particular live region to use the global settings.

  @param node: A hashable object representing the live region
  @type node: hashable
  @param settings: Name/value setting pairs. Either all settings or a subset to update.
  @type settings: dictionary
  '''

Probably need getters too.

Recommendation objects

class Recommendation(object):
  '''
  @ivar event_type: Type of event that triggered the recommendation
  @type event_type: integer
  @ivar node: Object the recommendation concerns
  @type node: hashable
  @ivar suggested_text: Suggested text to announce
  @type suggested_text: string
  @ivar all_text: All text in the live region
  @type all_text: string
  '''

What else?