[This is preliminary documentation and subject to change.]
The term "navigation," when used in the context of accessible objects, refers to the process of retrieving the address of another object's IAccessible or IDispatch interface using the methods provided by the current object.
Hierarchical Object Navigation
Often, client applications must move between objects based on their parent-child relationships. For example, an accessibility aid might already have information about a toolbar control, but not yet know anything about the buttons or other controls contained within it.
The IAccessible interface exposes the hierarchical relationships between objects through the IAccessible::get_accParent and IAccessible::get_accChild methods. Using these methods, client applications can navigate from a parent object to its children or vice versa.
Spatial and Logical Object Navigation
Applications can retrieve information about an object that is spatially or logically near the current object by using the IAccessible::accNavigate method. Using this method, a client can navigate to another object based on its location on the screen (spatial) or to the object that logically precedes or follows the current object, as determined by the server (logical). The client application specifies the type and direction to navigate by using navigational constants when calling the method.
The two types of navigation are very different. Spatial navigation is simple in concept; if a client wants the object to the right of the current one, the server retrieves it and gives it to the client. However, since logical relationships between objects are subjective, logical navigation is less straightforward for both the client and server. Generally, these relationships parallel those in keyboard navigation. For example, imagine a typical dialog box that contains a few edit controls, an OK button and a Cancel button. In this case, calling the IAccessible::accNavigate method to move to the next or previous object in the dialog box is analogous to the user pressing tab or shift+tab. That is, when the user presses tab, the system moves focus to the next object, and when the user presses shift+tab, the system moves the focus to the previous object.
When performing spatial navigation, clients must be aware of all floating objects. Because a floating object isn't clipped to its parent, you can't be sure of the hierarchical relationship between two objects near one another on the screen.
The following illustration shows this example of a floating object that isn't clipped to its parent.
Object Navigation Through Hit Testing
Applications can retrieve information about a child object by hit testing a point on the screen. To do this, call the current object's IAccessible::accHitTest method, passing the screen location to be hit tested in x- and y-coordinates. After the call, the pvarChild parameter points to a VARIANT structure that describes the hit test's result. If the call succeeds, the VARIANT structure's ppdispVal member is the address of the child object's IDispatch interface.
If multiple child objects overlap at a specified point, the accHitTest method retrieves the one that visually appears to occupy the space. However, accHitTest does not account for overlapping windows or clipping performed by the parent. Therefore, if a window covers a child object, hit testing the covered point will successfully retrieve the child object, even though it isn't actually visible at that point.
Additionally, the accHitTest method retrieves information about the topmost child object under the specified point. For example, if a child object displays a child of its own at the given point, only the top-level child object's information is returned.
Like any on-screen graphic, accessible objects can vary in shape. This isn't usually a problem, since most on-screen entities are well represented by rectangles. Rectangles can accurately describe most applications and their components: the application window, the menu, dialog boxes, buttons, scroll bars, and other common controls. As a result, accessible objects currently provide location information in terms of rectangles (by way of the IAccessible::accLocation method). If an object isn't shaped like a rectangle, the accLocation method provides the rectangle that contains the object.
Occasionally, rectangles aren't accurate enough. Accessible objects support the IAccessible::accHitTest method to provide access to clients on a pixel-by-pixel basis. This comes in handy when your application is tracking the location of the mouse pointer to gather information. The following illustration shows the relationship between an eccentric object's region and its bounding rectangle.
