AutomationProperties Class

Definition

Provides support for getting or setting instance-level values of automation properties. These property values are set as attached properties (typically in XAML) and supplement or override automation property values from a control's AutomationPeer.

public ref class AutomationProperties sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class AutomationProperties final
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class AutomationProperties
Public NotInheritable Class AutomationProperties
Inheritance
Object Platform::Object IInspectable AutomationProperties
Attributes

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

Tip

Open the WinUI 3 Gallery app and see the following Accessibility principles in action:

The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub

Remarks

AutomationProperties is the host service class for several XAML attached properties. The purpose of these attached properties is to enable setting various per-instance values that are pertinent to how a UI element is reported to the Microsoft UI Automation accessibility framework. This is useful in cases where the class design of the UI element doesn't already forward other UI-related property values as part of its Microsoft UI Automation integration or peer implementation behavior, or where the value being forwarded is not the value you want to report to Microsoft UI Automation.

In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods, which are also members of AutomationProperties. For example, the GetName and SetName methods support and provide the equivalent code-only support for reporting automation Name values to Microsoft UI Automation, instead of using the Name attached property to set it in XAML. Alternatively, you can use the dependency property system to get or set the value of the attached property, and this also reports the underlying value to Microsoft UI Automation. Call GetValue or SetValue, passing the arguments of the dependency property identifier to set, and a reference to the target object on which to get or set the value.

Name property

Of the various attached properties, probably the most important one is Name. This is because it is the Name property that is most frequently accessed and reported by assistive technology when users interact with an app in an accessibility scenario. The Name serves as the human-readable identifier for the UI element.

Various UI elements have peer forwarding that can provide a default Name value based on other element properties. For example, the peer forwarding for the Button class will forward the ToString evaluation of the Button content and use this string as the default Name. In order to override that default, or to otherwise provide a Name value for any UI element case where there is no Microsoft UI Automation Name available, set the Name attached property on that element in XAML. For more info on why a Microsoft UI Automation Name is important, see Basic accessibility information. For more info on how to test whether an element already has a peer-supplied Name that is useful, see Accessibility testing.

For localization reasons, you should avoid hard-coded string values for the Name in XAML. If you set x:Uid directive on the element, then you can use RESW resources to target the property and provide different values for localization. For attached properties, the resource identifier form requires full qualification of the attached property in XAML form, including its namespace and a using: prefix. For example, to target the AutomationProperties.Name attached property value on a resource that has x:Uid directive value of "sendButton", the name value of the data item in the RESW resources is sendButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name

See Attached properties for a complete list (for more info about each attached property, see each property's Identifier field).

Version history

Windows version SDK version Value added
1511 10586 GetLandmarkType
1511 10586 GetLocalizedLandmarkType
1511 10586 SetLandmarkType
1511 10586 SetLocalizedLandmarkType
1607 14393 GetDescribedBy
1607 14393 GetFlowsFrom
1607 14393 GetFlowsTo
1607 14393 GetFullDescription
1607 14393 GetIsDataValidForForm
1607 14393 GetIsPeripheral
1607 14393 GetLocalizedControlType
1607 14393 SetFullDescription
1607 14393 SetIsDataValidForForm
1607 14393 SetIsPeripheral
1607 14393 SetLocalizedControlType
1703 15063 GetCulture
1703 15063 SetCulture
1803 17134 GetHeadingLevel
1803 17134 SetHeadingLevel
1809 17763 GetIsDialog
1809 17763 SetIsDialog

Properties

AcceleratorKeyProperty

Identifies the AutomationProperties.AcceleratorKey attached property.

AccessibilityViewProperty

Identifies the AutomationProperties.AccessibilityView attached property.

AccessKeyProperty

Identifies the AutomationProperties.AccessKey attached property.

AnnotationsProperty

Identifies the AutomationProperties.Annotations attached property.

AutomationControlTypeProperty

Identifies the AutomationProperties.AutomationControlType attached property.

AutomationIdProperty

Identifies the AutomationProperties.AutomationId attached property.

ControlledPeersProperty

Identifies the AutomationProperties.ControlledPeers attached property.

CultureProperty

Identifies the AutomationProperties.Culture attached property.

DescribedByProperty

Identifies the AutomationProperties.DescribedBy attached property.

FlowsFromProperty

Identifies the FlowsFrom attached property.

FlowsToProperty

Identifies the FlowsTo attached property.

FullDescriptionProperty

Identifies the AutomationProperties.FullDescription XAML attached property.

HeadingLevelProperty

Identifies the HeadingLevel XAML attached property.

HelpTextProperty

Identifies the AutomationProperties.HelpText XAML attached property.

IsDataValidForFormProperty

Identifies the AutomationProperties.IsDataValidForForm XAML attached property.

IsDialogProperty

Identifies the AutomationProperties.IsDialog XAML attached property.

IsPeripheralProperty

Identifies AutomationProperties.IsPeripheral XAML attached property.

IsRequiredForFormProperty

Identifies the AutomationProperties.IsRequiredForForm XAML attached property.

ItemStatusProperty

Identifies the AutomationProperties.ItemStatus XAML attached property.

ItemTypeProperty

Identifies the AutomationProperties.ItemType XAML attached property.

LabeledByProperty

Identifies the AutomationProperties.LabeledBy XAML attached property.

LandmarkTypeProperty

Identifies the AutomationProperties.LandmarkType XAML attached property.

LevelProperty

Identifies the AutomationProperties.Level XAML attached property.

LiveSettingProperty

Identifies the AutomationProperties.LiveSetting XAML attached property.

LocalizedControlTypeProperty

Identifies the AutomationProperties.LocalizedControlType XAML attached property, which is a text string describing the type of control that the automation element represents.

LocalizedLandmarkTypeProperty

Identifies the AutomationProperties.LocalizedLandmarkType XAML attached property.

NameProperty

Identifies the AutomationProperties.Name XAML attached property.

PositionInSetProperty

Identifies the AutomationProperties.PositionInSet XAML attached property.

SizeOfSetProperty

Identifies the AutomationProperties.SizeOfSet XAML attached property.

Attached Properties

AcceleratorKey

Gets or sets a string containing the accelerator key (also called shortcut key) combinations for the automation element.

AccessibilityView

Gets or sets the Microsoft UI Automation tree view mode for an element.

AccessKey

Gets or sets a string containing the access key character for the automation element.

Annotations

Gets a list of annotation objects in a document, such as comment, header, footer, and so on.

AutomationControlType

Gets or sets the control type for Microsoft UI Automation.

AutomationId

Gets or sets the string that uniquely identifies the element to Microsoft UI Automation.

ControlledPeers

Gets a collection of automation elements that can be manipulated by the specified automation element.

Culture

Gets or sets the locale identifier for the automation element (for example, 0x0409 for "en-US" or English (United States)).

DescribedBy

Gets an array of elements that provide more information about the automation element.

FlowsFrom

Gets an array of automation elements that suggests the reading order before the current automation element.

FlowsTo

Gets an array of automation elements that suggests the reading order after the current automation element.

FullDescription

Gets or sets a localized string containing extended description text for an element.

HeadingLevel

Gets or sets the heading level for a UI Automation element.

HelpText

Gets or sets a help text string associated with the automation element.

IsDataValidForForm

Gets or sets a value that indicates whether the data is valid for the form.

IsDialog

Gets or sets a value that indicates whether the automation element is a dialog window.

IsPeripheral

Gets or sets a value that indicates whether the automation element represents peripheral UI.

IsRequiredForForm

Gets or sets a value that indicates whether the element is required to be filled out on a form.

ItemStatus

Gets or sets a description of the status of an item in an element.

ItemType

Gets or sets a description of the type of the specified element.

LabeledBy

Gets or sets the automation element that contains the text label for this element.

LandmarkType

Gets or sets a Landmark Type Identifier associated with an element.

Level

Gets or sets a 1-based integer that describes the location of an element inside hierarchical or broken hierarchical structures.

LiveSetting

Gets or sets the live setting value for the specified element, which is supported by an automation element that represents a live region.

LocalizedControlType

Gets or sets a localized text string that describes the type of control that the automation element represents.

LocalizedLandmarkType

Gets or sets a localized text string that describes the type of landmark that the automation element represents.

Name

Gets or sets the UI Automation name of the element.

PositionInSet

Gets or sets a 1-based integer that describes the ordinal location of the element within a set of elements that are considered to be siblings.

SizeOfSet

Gets or sets the number of elements in a set of elements that are considered to be siblings.

Methods

GetAcceleratorKey(DependencyObject)

Gets the value of the AutomationProperties.AcceleratorKey attached property for the specified DependencyObject.

GetAccessibilityView(DependencyObject)

Gets the value of the AutomationProperties.AccessibilityView attached property for the specified DependencyObject.

GetAccessKey(DependencyObject)

Gets the value of the AutomationProperties.AccessKey attached property for the specified DependencyObject.

GetAnnotations(DependencyObject)

Gets the value of the AutomationProperties.Annotations property for the specified DependencyObject.

GetAutomationControlType(UIElement)

Gets the value of the AutomationProperties.AutomationControlType attached property for the specified DependencyObject.

GetAutomationId(DependencyObject)

Gets the value of the AutomationProperties.AutomationId attached property for the specified DependencyObject.

GetControlledPeers(DependencyObject)

A static utility method that retrieves the list of controlled peers from a target owner.

GetCulture(DependencyObject)

Gets the value of the Culture XAML attached property for the specified DependencyObject.

GetDescribedBy(DependencyObject)

Gets a collection of elements that provide more information about the specified automation element.

GetFlowsFrom(DependencyObject)

Gets a list of automation elements that suggests the reading order before the specified automation element.

GetFlowsTo(DependencyObject)

Gets a list of automation elements that suggests the reading order after the specified automation element.

GetFullDescription(DependencyObject)

Gets the value of the AutomationProperties.FullDescription property for the specified DependencyObject.

GetHeadingLevel(DependencyObject)

Gets the value of the AutomationProperties.HeadingLevel property for the specified DependencyObject.

GetHelpText(DependencyObject)

Gets the value of the AutomationProperties.HelpText attached property for the specified DependencyObject.

GetIsDataValidForForm(DependencyObject)

Gets the value of the AutomationProperties.IsDataValidForForm property for the specified DependencyObject.

GetIsDialog(DependencyObject)

Gets the value of the AutomationProperties.IsDialog attached property for the specified DependencyObject.

GetIsPeripheral(DependencyObject)

Gets a Boolean value that indicates whether the specified element represents peripheral UI.

GetIsRequiredForForm(DependencyObject)

Gets the value of the AutomationProperties.IsRequiredForForm attached property for the specified DependencyObject.

GetItemStatus(DependencyObject)

Gets the value of the AutomationProperties.ItemStatus attached property for the specified DependencyObject.

GetItemType(DependencyObject)

Gets the value of the AutomationProperties.ItemType attached property for the specified DependencyObject.

GetLabeledBy(DependencyObject)

Gets the value of the AutomationProperties.LabeledBy attached property for the specified DependencyObject.

GetLandmarkType(DependencyObject)

Gets the value of the landmark type attached property for the specified DependencyObject.

GetLevel(DependencyObject)

Gets the value of the AutomationProperties.Level property for the specified element.

GetLiveSetting(DependencyObject)

Gets the value of the AutomationProperties.LiveSetting attached property for the specified DependencyObject.

GetLocalizedControlType(DependencyObject)

Gets a localized string that indicates the type of the specified control.

GetLocalizedLandmarkType(DependencyObject)

Gets the value of the localized landmark type attached property for the specified DependencyObject.

GetName(DependencyObject)

Gets the value of the AutomationProperties.Name attached property for the specified DependencyObject.

GetPositionInSet(DependencyObject)

Gets the value of the AutomationProperties.PositionInSet property for the specified DependencyObject.

GetSizeOfSet(DependencyObject)

Gets the value of the AutomationProperties.SizeOfSet property for the specified DependencyObject.

SetAcceleratorKey(DependencyObject, String)

Sets the value of the AutomationProperties.AcceleratorKey attached property for the specified DependencyObject.

SetAccessibilityView(DependencyObject, AccessibilityView)

Sets the value of the AutomationProperties.AccessibilityView attached property for the specified DependencyObject.

SetAccessKey(DependencyObject, String)

Sets the value of the AutomationProperties.AccessKey attached property for the specified DependencyObject.

SetAutomationControlType(UIElement, AutomationControlType)

Sets the value of the AutomationProperties.AutomationControlType attached property for the specified DependencyObject.

SetAutomationId(DependencyObject, String)

Sets the value of the AutomationProperties.AutomationId attached property for the specified DependencyObject.

SetCulture(DependencyObject, Int32)

Sets the value of the Culture attached property for the specified DependencyObject.

SetFullDescription(DependencyObject, String)

Sets a localized string that describes the visual appearance or contents of the specified DependencyObject.

SetHeadingLevel(DependencyObject, AutomationHeadingLevel)

Sets the value of the AutomationProperties.HeadingLevel property for the specified DependencyObject.

SetHelpText(DependencyObject, String)

Sets the value of the AutomationProperties.HelpText attached property for the specified DependencyObject.

SetIsDataValidForForm(DependencyObject, Boolean)

Sets a Boolean value that indicates whether the entered or selected value is valid for the form rule associated with the specified element.

SetIsDialog(DependencyObject, Boolean)

Sets a Boolean value that indicates whether the specified element should be identified as a dialog window.

SetIsPeripheral(DependencyObject, Boolean)

Sets a Boolean value that indicates whether the specified element represents peripheral UI.

SetIsRequiredForForm(DependencyObject, Boolean)

Sets the value of the AutomationProperties.IsRequiredForForm attached property for the specified DependencyObject.

SetItemStatus(DependencyObject, String)

Sets the value of the AutomationProperties.ItemStatus attached property for the specified DependencyObject.

SetItemType(DependencyObject, String)

Sets the value of the AutomationProperties.ItemType attached property for the specified DependencyObject.

SetLabeledBy(DependencyObject, UIElement)

Sets the value of the AutomationProperties.LabeledBy attached property for the specified DependencyObject.

SetLandmarkType(DependencyObject, AutomationLandmarkType)

Sets the value of the landmark type attached property for the specified DependencyObject.

SetLevel(DependencyObject, Int32)

Sets the value of the AutomationProperties.Level attached property for the specified DependencyObject.

SetLiveSetting(DependencyObject, AutomationLiveSetting)

Sets the value of the AutomationProperties.LiveSetting attached property for the specified DependencyObject.

SetLocalizedControlType(DependencyObject, String)

Sets a localized string that indicates the type of the specified control.

SetLocalizedLandmarkType(DependencyObject, String)

Sets the value of the localized landmark type attached property for the specified DependencyObject.

SetName(DependencyObject, String)

Sets the value of the AutomationProperties.Name attached property for the specified DependencyObject.

SetPositionInSet(DependencyObject, Int32)

Sets the value of the AutomationProperties.PositionInSet attached property for the specified DependencyObject.

SetSizeOfSet(DependencyObject, Int32)

Sets the value of the AutomationProperties.SizeOfSet attached property for the specified DependencyObject.

Applies to

See also