Implementing the UI Automation Value Control Pattern
This topic introduces guidelines and conventions for implementing IValueProvider, including information about properties and methods. Links to additional references are listed at the end of the topic.
The Value control pattern is used to support controls that have an intrinsic value not spanning a range and that can be represented as a string. This string can be editable, depending on the control and its settings. For examples of controls that implement this control pattern, see Control Pattern Mapping for UI Automation Clients.
This topic contains the following sections.
- Implementation Guidelines and Conventions
- Required Members for IValueProvider
- Related Topics
Implementation Guidelines and Conventions
When implementing the Value control pattern, note the following guidelines and conventions:
Controls such as a list item or tree item must support the Value control pattern if the value of any of the items is editable, regardless of the current edit mode of the control. The parent control must also support the Value control pattern if the child items are editable. The following image shows an example of an editable list item.
.jpg "Example of an editable list item.")
Single-line edit controls support programmatic access to their contents by implementing IValueProvider. Multiline edit controls typically do not implement IValueProvider; instead they provide access to their content by implementing ITextProvider. IValueProvider can be implemented for multiline edit controls whose contents can be changed.
To retrieve the textual contents of a multiline edit control, the control must implement ITextProvider. However, ITextProvider does not support setting the value of a control.
IValueProvider does not support the retrieval of formatting information or substring values. Implement ITextProvider in these scenarios.
IValueProvider must be implemented by controls such as the color picker selection control from Microsoft Word (see the following image), which supports string mapping between a color value (for example, "yellow") and an equivalent internal RGB structure.
.jpg "Example of color swatch string mapping.")
A control should have its IUIAutomationElement::CurrentIsEnabled (or IUIAutomationElement::CachedIsEnabled) property set to TRUE and its IValueProvider::IsReadOnly property set to FALSE before allowing a call to IValueProvider::SetValue.
Required Members for IValueProvider
The following properties and methods are required for implementing the IValueProvider interface.
| Required members | Member type | Notes |
|---|---|---|
| IValueProvider::IsReadOnly | Property | None |
| IValueProvider::Value | Property | None |
| IValueProvider::SetValue | Method | None |
This control pattern has no associated events.