Implementing the UI Automation Scroll Control Pattern
This topic introduces guidelines and conventions for implementing IScrollProvider, including information about properties and methods. Links to additional references are listed at the end of the topic.
The Scroll 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. The following image shows a scrolling control that does not use scrollbars. For examples of controls that implement this control pattern, see Control Pattern Mapping for UI Automation Clients.
.jpg "Image of a scrolling control that does not use scrollbars.")
This topic contains the following sections.
- Implementation Guidelines and Conventions
- Required Members for IScrollProvider
- 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 Scroll control pattern. They must support the RangeValue 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.
- The IScrollProvider::HorizontallyScrollable property and IScrollProvider::VerticallyScrollable property are independent of the IUIAutomationElement::CurrentIsEnabled (or IUIAutomationElement::CachedIsEnabled property.
- If the IScrollProvider::HorizontallyScrollable property is FALSE, the IScrollProvider::HorizontalViewSize property should be set to 100% and IScrollProvider::HorizontalScrollPercent property should be set to NoScroll. Likewise, if the IScrollProvider::VerticallyScrollable property is FALSE, the IScrollProvider::VerticalViewSize property should be set to 100 percent and IScrollProvider::VerticalScrollPercent property should be set to NoScroll. This allows a Microsoft UI Automation client to use these property values within the IScrollProvider::SetScrollPercent method while avoiding a race condition if a direction the client is not interested in scrolling becomes activated.
- The IScrollProvider::HorizontalScrollPercent property is locale-specific. Setting IScrollProvider::HorizontalScrollPercent to 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 IScrollProvider::HorizontalScrollPercent to 100.0 must set the scroll location to the leftmost position.
Required Members for IScrollProvider
The following properties and methods are required for implementing the IScrollProvider interface.
| Required members | Member type | Notes |
|---|---|---|
| IScrollProvider::HorizontalScrollPercent | Property | None |
| IScrollProvider::VerticalScrollPercent | Property | None |
| IScrollProvider::HorizontalViewSize | Property | None |
| IScrollProvider::VerticalViewSize | Property | None |
| IScrollProvider::HorizontallyScrollable | Property | None |
| IScrollProvider::VerticallyScrollable | Property | None |
| IScrollProvider::Scroll | Method | None |
| IScrollProvider::SetScrollPercent | Method | None |
This control pattern has no associated events.