Implementing the UI Automation Value Control Pattern

Artigo
08/01/2011

Observação

Esta documentação destina.Os desenvolvedores do NET Framework que desejam usar o gerenciado UI Automation classes definidas na System.Windows.Automation namespace.As informações mais recentes sobre UI Automation, consulte API de automação do Windows: Automação da interface do usuário.

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

The ValuePattern 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 pattern, see Mapeamento de Padrão de Controles para Clientes de Automação de IU.

Este tópico contém as seguintes seções.

Implementation Guidelines and Conventions
Required Members for IValueProvider
Exceptions
Tópicos relacionados

Implementation Guidelines and Conventions

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

Controls such as ListItem and TreeItem must support ValuePattern 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 ValuePattern if the child items are editable.

Example of an Editable List Item

Item de lista editável.

Single-line edit controls support programmatic access to their contents by implementing IValueProvider. However, multi-line edit controls do not implement IValueProvider; instead they provide access to their content by implementing ITextProvider.
To retrieve the textual contents of a multi-line 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 (illustrated below), which supports string mapping between a color value (for example, "yellow") and an equivalent internal RGB structure.

Example of Color Swatch String Mapping

Seletor de cores com amarelo realçado.

A control should have its IsEnabledProperty set to true and its IsReadOnlyProperty set to false before allowing a call to SetValue.

Required Members for IValueProvider

The following properties and methods are required for implementing IValueProvider.

Required members	Member type	Notes
IsReadOnlyProperty	Property	None
ValueProperty	Property	None
SetValue	Method	None

Exceptions

Providers must throw the following exceptions.

Exception type	Condition
InvalidOperationException	SetValue If locale-specific information is passed to a control in an incorrect format such as an incorrectly formatted date.
ArgumentException	SetValue If a new value cannot be converted from a string to a format the control recognizes.
ElementNotEnabledException	SetValue When an attempt is made to manipulate a control that is not enabled.

InvalidOperationException

SetValue