2.1.1   pyLinAcc

Purpose

• To create a connection to the Assistive Technology Service Provider Interface (AT-SPI) desktop accessibility registry daemon
• To provide a system for managing and dispatching raw AT-SPI accessibility events
• To do automatic reference counting on all AT-SPI accessible objects
• To define convenience methods for querying AT-SPI interfaces and performing other common AT-SPI specific tasks (e.g. searching)
• To expose a list of all raw event types that can be logged by AEMonitors

Description

The pyLinAcc component creates a connection to the AT-SPI registry daemon when it is initialized. The EventManager uses the pyLinAcc event sub-components to register for raw accessibility events when the system starts. pyLinAcc notifies the EventManager of all events of interest thereafter.

pyLinAcc also "mixes" additional behavior into the AT-SPI class definitions during initialization. This "mixin" code does automatic reference counting on all accessibles and adds convenience methods such as searching for an accessible matching a given boolean expression.

Portability

The pyLinAcc package is specific to AT-SPI. This component needs to be replaced if the engine is ported to a platform using a different accessibility architecture.

Source

• pyLinAcc package

2.1.2   AEEvent

Purpose

• To wrap raw accessibility events in internal, platform agnostic interfaces
• To define the origin of an event as being at the focus POR, in the active Tier, or in a background Tier exclusively,
• To provide an execution method that informs one or more components of the occurrence of the event
• To expose a list of all AEEvent types that can be logged by AEMonitors.

Adapters create AEEvents in response to raw accessibility events dispatched by pyLinAcc to the ViewManager. The ViewManager posts these AEEvents to the EventManager for later execution. The EventManager executes these AEEvents, which in turn call methods in the ViewManager and TierManager. The information carried by AEEvents is ultimately delivered to one or more Tasks registered to observe it.

AEEvents are defined as occuring on one of three mutually exclusive layers. Events on the focus layer originate from the POR that had the application focus when the event was generated. Events on the tier layer originate from a POR in an application that was active when the event was generated. Events on the background layer originate from a POR in an application that was inactive when the event was generated. Tasks can register to receive AEEvents on any one or more of these layer.

The following are the defined AEEvents:

CaretChange

Indicates a caret move, text insertion, or text deletion. Provides a POR to new location of the caret, the offset of the caret from the start of the line of text, an indicator of whether text was inserted or deleted or if the caret only moved, and the actual text string inserted or deleted.

ChildrenChange

Indicates the insertion or removal of accessible children. Provides a POR to the parent, an indicator of whether a child was inserted or deleted, and a POR to the child.

ChooserChange

Indicates a change in the state of an AEChooser dialog. Provides a signal value identifying the kind of change along with additional data given by the chooser.

FocusChange

Indicates a change of focus, gained or lost. Provides a POR to an accessible and indicator of whether it gained or lost the focus.

InputGesture

Indicates a gesture on an input device. Provides the time at which the gesture occurred relative to a device absolute zero and any data packaged in the event by the AEInput device that created it.

MouseChange

Indicates a mouse movement, button press, button release, or button click event. Provides the event type and a the (x,y) coordinate for movement.

PropertyChange

Indicates a change in a simple (text or numeric) property of an accessible. Provides a POR pointing to the object that changed properties, the name of the property changed, and its new value.

ScreenChange

Indicates a change in the visibility or bounds of an accessible or item on the screen. Provides a POR to the changed object and the kind of visual change that occurred.

SelectorChange

Indicates a change in the active item, multiple selection, or text selection. Provides a POR to the selected item, its text, and the kind of selection change.

StateChange

Indicates a change in state in an item or accessible. Provides a POR to the changed object, the name of the state that changed, and an indicator of whether the state was gained or lost.

TableChange

Indicates a change in the structure of a table. Provides a POR to the table, whether the change affects rows or columns, whether the change is an insertion, deletion, or move; a POR to the first row/column affected, and a POR to the last row/column affected.

TimerAlert

Indicates a timed interval of importance to a Task has elapsed. Provides the interval requested, not the exact time passed.

ViewChange

Indicates a change in view, the active foreground window, panel, frame, etc. Provides a POR to the root of the view and an indicator of whether the root gained the view, lost the view, is the first view when the engine starts, or is an application having one or more associated Perks which may be interested in events when the application is not in the view.

Source

• AEEvent package

2.2.1   Point of Regard (POR)

Purpose

• To refer to an accessible widget
• To refer to an item within that widget
• To refer to a character within that item or accessible

Description

The concept of a POR is at the heart of how the nengine maintains context for system events and user interaction. A POR consists of three pieces of information: an accessible object, an item offset, and a character offset:

accessible

A proxy object representing a complete widget in an application with methods for querying its properties, and, in some cases, manipulating the widget. Buttons, list boxes, combo boxes, text areas, and menus are all examples of accessible objects. An accessible may contain any number of items and have any number of other accessibles as children. An accessible is a child of at most one parent at a time.

item

An element contained or embedded in an accessible widget and referred to by an index (the item offset) relative to the first available item. List items, table cells, tree items, and lines of text in a text control are examples of items. An item typically has no accessible children and does not contain other items, only strings of characters. The major exception to this rule is in hypertext where a line of text may embed an image, a link, a table, and so on. An item is an element in exactly one accessible parent at a time.

character

An atomic, semantic symbol within a unicode string of text referred to by an index (the character offset) relative to the first character in an item or the accessible itself.

When a POR contains an accessible but no item offset, it refers to the accessible itself, regardless of whether it contains items. When a POR contains an accessible and an item offset, it refers to the particular item at the given offset in the accessible container. When the character offset is non-zero, it refers to a single character within either the accessible or the item within the accessible.

Portability

PORs are platform independent. Any object may be stored in the accessible slot while the item and character offsets are simple integers. How and when the last two slots are used across platforms may vary, but the structure itself will not. It is the responsibility of the Adapters to populate and interpret the fields of a POR consistently on a given platform.

Source

• POR module

2.2.2   Adapters

• To create AEEvents in response to raw accessibility events
• To adapt platform specific accessibility interfaces to one set of internal interfaces
• To produce PORs which can be later interpreted by other Adapters as indicating specific accessibles, items, and characters on the desktop

On startup, all available Adapters are registered with a central dispatcher. Each Adapter is registered under the interfaces it provide. When the ViewManager, a Walker, or a TaskTools method wishes to wrap an accessible or POR in a particular interface, the Adapter dispatcher selects an appropriate Adapter based on the requested interface and preconditions defined by the Adapter itself. If no Adapter precondition is satisfied, a default Adapter is selected for use instead.

The engine defines the following interfaces:

IAccessibleInfo

Defines methods for retrieving information about PORs.

IAccessibleNav

Defines methods for navigating among accessibles.

IItemNav

Defines methods for navigating among items within accessibles.

IAccessibleAction

Defines methods for manipulating PORs

IEventHandler

Defines methods for handling accessible events.

IPORFactory

Defines methods for creating valid PORs given an existing object such as an accessible or another POR.

Perks never use Adapters directly. Instead, Perks call TaskTools methods which act on PORs using available Adapters.

Portability

Adapters are written to target specific accessibility APIs. A set of AT-SPI Adapters for Linux will not port to Windows, for example. However, new Adapters for MSAA, IAccessible2, and other APIs could be written. Adding new adapters increases the number of platforms on which the TaskTools will work without requiring a change in Perks.

Source

• Adapters package
• AEInterfaces module
• AccAdapt module

2.2.3   Walker

Purpose

• To define an interface for walking the hierarchy of widgets in a well-defined order
• To provide some basic, well-defined walk orders

Description

A Walker is created by TaskTools to retrieve the next, previous, parent, first, or last POR given a starting reference POR. The fetched POR points to an accessible and/or item having the specified relationship to the reference and based on the properties and implementation of the Walker.

Two walker implementations are provided in the core. The AccessibleWalker iterates over all parent-child relationships in the accessible hierarchy given a starting POR. The definition of an item is ignored by this Walker.

The AccessibleItemWalker traverses accessibles and their items given a starting POR in the accessible hierarchy. It can be set to navigate over:

• non-trivial, visible accessibles and items only,
• visible accessibles and items only,
• non-trivial, accessibles and items only, or
• all accessibles and items.

The walk order of accessibles and items is best defined as an in-order traversal of the accessible hierarchy. The implementation is actually more complex, though, to account for embedded items in hypertext. The following diagrams depict the forward and backward AccessibleItemWalker state machines:

Figure: The forward walk state machine. Circles indicate methods invoked on the AccessibleItemWalker. Squares indicated adapter methods invoked during processing.

Figure: The backward walk state machine. Circles indicate methods invoked on the AccessibleItemWalker. Squares indicated adapter methods invoked during processing.

Other Walkers can be defined to traverse the hierarchy in other orders and manners. For instance, a DocumentWalker might traverse text following text flow relationships instead of parent-child connections. Similarly, a VisibleWalker might respect the visual layout of a window.

The Walkers use the IAccessibleNav and IItemNav interfaces to walk through widgets and items in the accessible hierarchy. Appropriate Adapters are selected for use based on the type of accessible currently being traversed. The definition of an item is determined by the Adapter selected. In a text accessible, a line is the default definition of an item. In a tree, list, or table, an item is a cell at a row/column intersection. In simple accessibles, there is only one item: the accessible itself.

Source

• Walker package

2.3.1   Tier

Purpose

• To manage stacks of Perks processing events for an application
• To execute Tasks registered in Perks

Description

A Tier is created by the TierManager when a desktop application window is first activated. The TierManager dispatches AEEvents to a Tier for processing by its registered Perks and Tasks.

A Tier iterates from top to bottom over its Perks looking for Tasks to execute in response to a given AEEvent. Before executing any Tasks within a Perk, the Tier provides the TaskTools with important references to other components so that its methods may operate properly.

A Tier also executes Tasks invoked by name by other Perks and Tasks. When invoking a Task by name, a Tier first determines if other Tasks are chained to it so that they may execute before, after, or around the named Task. As with AEEvents, the Tier initializes the TaskTools before executing any and all Tasks.

The value returned from Task execution indicates whether Task execution should continue or not for the current event or chain. If the return value is false, the Tier invokes a special update housekeeping method on all remaining Tasks instead of executing them.

Source

• Tier module

2.3.2   TaskTools

Purpose

• To provide convenience methods for giving output, getting input, retrieving accessibility information, performing accessible actions, and managing user interface elements
• To shield Perk developers from intricacies of the desktop accessibility architecture

Description

Perks and Tasks call TaskTool methods during their execution. Some methods use the available Adapters to get and manipulate accessible widgets on the desktop. Other methods contact the DeviceManager to communicate with and configure input and output devices. Still others invoke methods on the UIRegistrar to manage user interface elements.

The TaskTools methods are pre-configured by a Tier before the execution of a Perk or Task. The TaskTools are provided with important references, such as the parent Tier, the POR associated with an event originating on the desktop, all managers, and so on.

Source

• TaskTools package

2.5.1   AEState

Purpose

• To define an interface that must be provided by any state object that has values configurable by the user or persistent on disk
• To define methods for adding metadata to settings such as labels, descriptions, and types

Description

The AEState component itself performs no actions. It is an interface that an state class must implement to support configuration by the user and persistence on disk.

A state object that implements AEState can be used to generate configuration dialogs and enable the persistence of data by the SettingsManager. Perks may define classes that implement AEState to support the changing and persistence of Perk specific settings. AEInput and AEOutput devices may do the same.

Source

• AEState package

4.1.1   Task

Purpose

• To implement a portion of the user interface defined by a Perk
• To execute in response to AEEvents
• To execute before, after, or around other Tasks
• To expose a list of all Task types that can be logged by AEMonitors.

Description

A Task is executed by the Tier containing the Perk that registered it. Before executing a Task, the Tier configures the TaskTools with information about the current POR, Perk settings, and Tier state. During execution, the Task uses the TaskTools to query accessibility information, give output, change the state of the system, manipulate how other Tasks will execute, and so forth.

A Perk typically registers Tasks during its initialization as handlers for AEEvents. The following Tasks are defined in correspondence with the available AEEvents:

• CaretTask
• ChildrenTask
• FocusTask
• InputTask
• PropertyTask
• ScreenTask
• SelectorTask
• StateTask
• TableTask
• TimerTask
• ViewTask

Event handling Tasks are executed in the order defined by the Perk stack. Perks at the top of the stack are typically specific to an application and handle events first. More general Perks are located at the bottom of the stack and handle events last.

A Task may be registered to handle AEEvents on any combination of the focus, tier, and background layers. For instance, the GaimPerk registers a CaretTask for events on the tier and focus layers. The effect of this registration is that incoming messages are announced whether the message history has the focus or not as long as one of the gaim windows is active (i.e. when it is not in the background).

A Perk may also register Tasks with names unique across an entire Tier. Named Tasks may be referenced by any Perk within the Tier and may be associated with input gestures from an AEInput device. Tasks in other Perks may invoke a Task in the same Tier by its name.

Named Tasks may also be chained to other named Tasks. A chained Task may execute before, after, or around its anchor, the Task to which it is chained. A Task chained before its anchor has the ability to prevent later Tasks in the chain from executing. A Task chained after has the ability to modify the return value from earlier Tasks. A Task chained around the anchor has the ability to manipulate both the parameters and return value given to the anchor, or to prevent the anchor from running at all.

Source

• Task package