Creating UI Automation Client Applications (Cont.)

UI Automation Properties for Clients

Properties of IUIAutomationElement objects contain information about UI elements, usually controls. The properties of an element are generic to all elements and not specific to a control type. Control patterns, discussed later, expose control-specific properties.

UI Automation properties are read-only. To set properties of a control, you must use the methods of the appropriate control pattern; for example, use the IScrollProvider::Scroll method to change the position values of a scrolling window.

To improve performance, you can cache property values of controls and control patterns when you retrieve elements.

Some generic properties, and all control pattern properties, are available as properties on the IUIAutomationElement interface or control pattern interface, and you can retrieve them with accessor methods.

When using the generic accessors, you must specify properties with the property identifiers defined in UIAutomationClient.h. You use them to specify properties when retrieving property values, constructing property conditions, and subscribing to property-changed events.

If a UI Automation provider does not implement a property, UI Automation is able to supply a default value for that property. For example, if the provider does not support the property identified by UIA_IsDockPatternAvailablePropertyId, UI Automation returns FALSE.

Control Patterns

Control patterns complement properties. Control patterns are collections of associated properties, events, and methods that describe an element. More than one pattern can apply to a single element.

A control pattern represents a collected group of capabilities. The pattern might be something simple like the Invoke pattern, which lets clients invoke a control. In contrast, the more complicated Value pattern supports getting and setting a control’s value, and then checking whether the value is read-only.

You can obtain a control pattern by calling the IUIAutomationElement::GetCurrentPattern or IUIAutomationElement::GetCurrentPatternAs method, or their cached versions. Once you get a control pattern interface, use it as you would the element itself, either by directly calling control pattern methods or by accessing control pattern properties.

The TurnItUp method in Listing 2 uses the RangeValue pattern to set a control (such as a volume slider) to its maximum value.

In addition to checking for errors when getting the current pattern, this example also checks for NULL because NULL is a valid return value when a control does not support the pattern requested.

Control Types

While a control type is mechanically a simple enumeration property, on a conceptual level it is much more important. An element’s control type is a broad classification of the control, such as button, window, or list box. Each control type has certain expected control patterns. For example, a button control should support either the Invoke pattern or the Toggle pattern, and a hyperlink should support the Invoke Pattern and possibly the Value pattern.

Some controls have conditional support for several control patterns. For example, the menu item control has conditional support for the Invoke, Expand Collapse, Toggle, and SelectionItem control patterns, depending on the menu item control’s function within the menu control.

Searching and Navigation

There are two major ways of getting to elements. The first is to use a Find method, which lets the UI Automation core minimize cross-process calls and improve searching time. The second is to use a tree walker to walk a UI tree.

Using Find Methods

The Find methods require three things: a parent element, a scope to search on, and (most importantly) a condition to search for.

You create conditions by calling various APIs on the CUIAutomation object. You can create simple Property conditions, or combine them with And, Or, and Not operators to produce more complex conditions.

Once you create a condition, you need to specify the element to start searching from and the search scope. The element you want to start from is the element on which you call the FindFirst or FindAll method. The search scope is typically one of three choices: the element itself, its children, or its descendants.

You usually want to limit search scope as much as possible to improve performance and to reduce the chance of finding an element you weren’t looking for.

Listing 3 is a simple example of searching for a named application window using FindFirst methods. In the example, the search condition (a particular name) is quite simple. However, conditions can be considerably more complex.

Using Tree Walkers

Another method for navigating through the tree is the use of tree walkers. Tree walkers allow use of direct-navigation methods such as moving between parent, child, and sibling to walk through a filtered view of the tree. There are several built-in filtered views:

• Raw or unfiltered, which shows all elements.
• Control view (the default), which filters out elements that either are redundant or are just used for layout.
• Content view, which filters controls even more selectively than Control view does.

Users can also create their own custom views with Conditions.

The following simple example shows how to walk to the first child of the control referenced by pElement:

UI Automation and Threading

Because of the way UI Automation uses Windows messages, conflicts can occur when a client application attempts to interact with its own UI on the UI thread. These conflicts can lead to very slow performance or even cause the application to stop responding.

If you intend your client application to interact with all elements on the desktop-including its own UI-you should make all UI Automation calls on a separate thread. This recommendation also applies when your application locates elements and uses control patterns.

It is safe to make UI Automation calls within a UI Automation event handler because the event handler is never called on a UI thread. However, when subscribing to events that may originate from your client application's UI, you must make the call on a non-UI thread. Remove event handlers on the same thread.