Makes some sense of the AT-SPI API

The tree API handles various things for you: - fixes most timing issues - can automatically generate (hopefully) highly-readable logs of what the script is doing - traps various UI malfunctions, raising exceptions for them (again, hopefully improving the logs)

The most important class is Node. Each Node is an element of the desktop UI. There is a tree of nodes, starting at root, with applications as its children, with the top-level windows and dialogs as their children. The various widgets that make up the UI appear as descendents in this tree. All of these elements (root, the applications, the windows, and the widgets) are represented as instances of Node in a tree (provided that the program of interest is correctly exporting its user-interface to the accessibility system). The Node class is a wrapper around Accessible and the various Accessible interfaces.

The Action class represents an action that the accessibility layer exports as performable on a specific node, such as clicking on it. It's a wrapper around AccessibleAction.

We often want to look for a node, based on some criteria, and this is provided by the Search class.

Dogtail implements a high-level searching system, for finding a node (or nodes) satisfying whatever criteria you are interested in. It does this with a backoff and retry algorithm. This fixes most timing problems e.g. when a dialog is in the process of opening but hasn't yet done so.

If a search fails, it waits Config.searchBackoffDuration seconds, and then tries again, repeatedly. After several failed attempts (determined by Config.searchWarningThreshold) it will start sending warnings about the search to the debug log. If it still can't succeed after Config.searchCutoffCount attempts, it raises an exception containing details of the search. You can see all of this process in the debug log by setting Config.debugSearching to True

We also automatically add a short delay after each action (Config.defaultDelay gives the time in seconds). We'd hoped that the search backoff and retry code would eliminate the need for this, but unfortunately we still run into timing issues. For example, Evolution (and probably most other apps) set things up on new dialogs and wizard pages as they appear, and we can run into setting wars where the app resets the widgetry to defaults after our script has already filled out the desired values, and so we lose our values. So we give the app time to set the widgetry up before the rest of the script runs.

The classes trap various UI malfunctions and raise exceptions that better describe what went wrong. For example, they detects attempts to click on an insensitive UI element and raise a specific exception for this.

Unfortunately, some applications do not set up the sensitive state correctly on their buttons (e.g. Epiphany on form buttons in a web page). The current workaround for this is to set Config.ensureSensitivity=False, which disables the sensitivity testing.

Authors: Zack Cerza <zcerza@redhat.com>, David Malcolm <dmalcolm@redhat.com>