Package dogtail :: Module tree
[hide private]
[frames] | no frames]

Module tree

source code

Makes some sense of the AT-SPI API

The tree API handles various things for you:

script is doing

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 mixin for 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 Accessibility.Action.

We often want to look for a node, based on some criteria, and this is provided by the Predicate 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 <>, David Malcolm <>

Author: Zack Cerza <>, David Malcolm <>

Classes [hide private]
The widget is not sensitive.
The widget does not support the requested action.
Class representing an action that can be performed on a specific node
A node in the tree of UI elements.
Class storing info about an anchor within an Accessibility.Hyperlink, which is in turn stored within an Accessibility.Hypertext.
Note that the buttons of a GnomeDruid were not accessible until recent versions of libgnomeui.
Variables [hide private]
  gotWnck = True
  haveWarnedAboutChildrenLimit = False
  root = <Accessible object at 0x2d5b820 (AtspiAccessible at 0x2...
  sniff_lock = Lock(lockname= 'sniff_refresh.lock', randomize= F...
  __package__ = 'dogtail'
Variables Details [hide private]


<Accessible object at 0x2d5b820 (AtspiAccessible at 0x2dc4dd0)>


Lock(lockname= 'sniff_refresh.lock', randomize= False)