Implementing the UI Automation Scroll Control Pattern

This topic introduces guidelines and conventions for implementing IScrollProvider, including information about events and properties. Links to additional references are listed at the end of the topic.

The ScrollPattern control pattern is used to support a control that acts as a scrollable container for a collection of child objects. The control is not required to use scrollbars to support the scrolling functionality, although it commonly does.

---

Example of a Scrolling Control that Does Not Use Scrollbars

For examples of controls that implement this control, see Control Pattern Mapping for UI Automation Clients.

This topic contains the following sections.

• Implementation Guidelines and Conventions
• Required Members for IScrollProvider
• Exceptions
• Related Topics

Implementation Guidelines and Conventions

When implementing the Scroll control pattern, note the following guidelines and conventions:

• The children of this control must implement IScrollItemProvider.

• The scrollbars of a container control do not support the ScrollPattern control pattern. They must support the RangeValuePattern control pattern instead.

• When scrolling is measured in percentages, all values or amounts related to scroll graduation must be normalized to a range of 0 to 100.

• HorizontallyScrollableProperty and VerticallyScrollableProperty are independent of the IsEnabledProperty.

• If HorizontallyScrollableProperty = false then HorizontalViewSizeProperty should be set to 100% and HorizontalScrollPercentProperty should be set to NoScroll. Likewise, if VerticallyScrollableProperty = false then VerticalViewSizeProperty should be set to 100 percent and VerticalScrollPercentProperty should be set to NoScroll. This allows a UI Automation client to use these property values within the SetScrollPercent method while avoiding a race condition if a direction the client is not interested in scrolling becomes activated.

• HorizontalScrollPercent is locale-specific. Setting HorizontalScrollPercent = 100.0 must set the scrolling location of the control to the equivalent of its rightmost position for languages such as English that read left to right. Alternately, for languages such as Arabic that read right to left, setting HorizontalScrollPercent = 100.0 must set the scroll location to the leftmost position.

Required Members for IScrollProvider

The following properties and methods are required for implementing IScrollProvider.

Required member	Member type	Notes
HorizontalScrollPercent	Property	None
VerticalScrollPercent	Property	None
HorizontalViewSize	Property	None
VerticalViewSize	Property	None
HorizontallyScrollable	Property	None
VerticallyScrollable	Property	None
Scroll	Method	None
SetScrollPercent	Method	None

This control pattern has no associated events.

Exceptions

Providers must throw the following exceptions.

Exception Type	Condition
ArgumentException	Scroll throws this exception if a control supports SmallIncrement values exclusively for horizontal or vertical scrolling, but a LargeIncrement value is passed in.
ArgumentException	SetScrollPercent throws this exception when a value that cannot be converted to a double is passed in.
ArgumentOutOfRangeException	SetScrollPercent throws this exception when a value greater than 100 or less than 0 is passed in (except -1 which is equivalent to NoScroll).
InvalidOperationException	Both Scroll and SetScrollPercent throw this exception when an attempt is made to scroll in an unsupported direction.

See Also

Tasks

Support Control Patterns in a UI Automation Provider
Use Caching in UI Automation

Concepts

UI Automation Control Patterns Overview
UI Automation Control Patterns for Clients
UI Automation Tree Overview