UI Automation Support for the TreeItem Control Type

Note

This documentation is intended for .NET Framework developers who want to use the managed UI Automation classes defined in the System.Windows.Automation namespace. For the latest information about UI Automation, see Windows Automation API: UI Automation.

This topic provides information about UI Automation support for the TreeItem control type. In UI Automation, a control type is a set of conditions that a control must meet in order to use the ControlTypeProperty property. The conditions include specific guidelines for UI Automation tree structure, UI Automation property values and control patterns.

The TreeItem control type represents a node within a tree container. Each node might contain other nodes, called child nodes. Parent nodes, or nodes that contain child nodes, can be displayed as expanded or collapsed.

The following sections define the required UI Automation tree structure, properties, control patterns, and events for the TreeItem control type. The UI Automation requirements apply to all tree item controls, whether Windows Presentation Foundation (WPF), Win32, or Windows Forms.

This topic contains the following sections.

  • Required UI Automation Tree Structure
  • Required UI Automation Properties
  • Required UI Automation Control Patterns
  • Required UI Automation Events
  • Related Topics

Required UI Automation Tree Structure

The following table depicts the control view and the content view of the UI Automation tree that pertains to tree item controls and describes what can be contained in each view. For more information on the UI Automation tree, see UI Automation Tree Overview.

Control View

Content View

TreeItem

  • CheckBox (0 or 1)

  • Image (0 or 1)

  • Button (0 or 1)

  • TreeItem (0 or more)

TreeItem

  • TreeItem (0 or more)

Tree item controls can have zero or more tree item children in the content view of the UI Automation tree. If the tree item control has functionality beyond what is exposed in the control patterns listed below, then the control should be based on the Data Item control type.

Collapsed tree items will not display in the control view or content view until they become expanded and visible (or, can be scrolled into view).

The control view can contain additional details for a control, including an associated image or a button. For example, an item in an outline view might contain an image as well as a button to expand or collapse the outline. These detail objects don't appear in the content view because the information is already represented by the parent tree item. Tree items that are scrolled off the screen will appear in both the control and content views of the UI Automation tree and should have the IsOffscreenProperty set to true.

Required UI Automation Properties

The following table lists the UI Automation properties whose value or definition is especially relevant to list controls. For more information on UI Automation properties, see UI Automation Properties for Clients.

UI Automation Property

Value

Notes

AutomationIdProperty

See notes.

The value of this property needs to be unique across all controls in an application.

BoundingRectangleProperty

See notes.

The outermost rectangle that contains the whole control.

ClickablePointProperty

See notes.

This property must return a location of the item that will cause the item to change selection state or become focused.

ControlTypeProperty

TreeItem

This value is the same for all UI frameworks.

IsContentElementProperty

True

The list control is always included in the content view of the UI Automation tree.

IsControlElementProperty

True

The list control is always included in the control view of the UI Automation tree.

IsOffscreenProperty

See notes.

This property is set to indicate when a tree item control is scrolled off the screen.

IsKeyboardFocusableProperty

See notes.

If the control can receive keyboard focus, it must support this property.

ItemTypeProperty

See notes.

If the tree item control uses a visual icon to indicate that is a particular type of object, then this property must be supported and indicate what the object is.

LabeledByProperty

Null

Tree item controls are self-labeling.

LocalizedControlTypeProperty

"tree item"

Localized string corresponding to the TreeItem control type.

NameProperty

See notes.

This property exposes the text displayed for each tree item control.

Required UI Automation Control Patterns

The following table lists the UI Automation control patterns required to be supported by list controls. For more information on control patterns, see UI Automation Control Patterns Overview.

Control Pattern/Pattern Property

Support/Value

Notes

IInvokeProvider

Depends

Implement this control pattern if the tree item has a separate, actionable command.

IExpandCollapseProvider

Yes

All tree items can be expanded or collapsed.

ExpandCollapseState

Expanded, Collapsed, or Leaf Node

Tree items will be leaf nodes when they are not expanded or collapsed.

IScrollItemProvider

Depends

Implement this control pattern if the tree container supports the Scroll control pattern.

ISelectionItemProvider

Depends

Implement this control pattern if it is possible to have an active selection that is maintained when the user returns to the tree container.

SelectionContainer

Yes

This property will expose the same container for all items within the container.

IToggleProvider

Depends

Implement this control pattern if the tree item has an associated check box.

Required UI Automation Events

The following table lists the UI Automation events required to be supported by all tree item controls. For more information about events, see UI Automation Events Overview.

UI Automation Event

Support

Notes

AutomationFocusChangedEvent

Required

None

BoundingRectangleProperty property-changed event.

Required

None

IsEnabledProperty property-changed event.

Required

None

IsOffscreenProperty property-changed event.

Required

None

ItemStatusProperty property-changed event.

Depends

None

NameProperty property-changed event.

Required

None

StructureChangedEvent

Required

None

ExpandCollapseStateProperty property-changed event.

Required

None

InvokedEvent

Depends

None

CurrentViewProperty property-changed event.

Depends

None

ElementAddedToSelectionEvent

Depends

None

ElementRemovedFromSelectionEvent

Depends

None

ElementSelectedEvent

Depends

None

ToggleStateProperty property-changed event.

Depends

None

ValueProperty property-changed event.

Depends

None

See Also

Reference

TreeItem

Concepts

UI Automation Control Types Overview

UI Automation Overview