AutomationPeer Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Automation.Peers

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Provides a base class that exposes the automation peer for an associated owner class to Microsoft UI Automation.

public ref class AutomationPeer : DependencyObject

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class AutomationPeer : DependencyObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class AutomationPeer : DependencyObject

Public Class AutomationPeer
Inherits DependencyObject

Inheritance: Object Platform::Object IInspectable DependencyObject AutomationPeer

Derived: Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer

Microsoft.UI.Xaml.Automation.Peers.ItemAutomationPeer

Microsoft.UI.Xaml.Automation.Peers.LoopingSelectorItemDataAutomationPeer

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Remarks

AutomationPeer is the class that provides almost all of the API that eventually forwards the Microsoft UI Automation information for a UWP app using C++, C#, or Visual Basic to a Microsoft UI Automation client. Typical Microsoft UI Automation clients aren't calling AutomationPeer methods directly. These clients are often assistive technology that are using other programming models and operating as services, and are not likely to be calling Windows Runtime methods. But the general Microsoft UI Automation support in the Windows Runtime forwards all this information using the provider side of the Microsoft UI Automation framework. Any clients to Microsoft UI Automation can interact with the representative automation trees of a UWP app using C++, C#, or Visual Basic.

Firing automation events

The AutomationPeer class is relevant to Windows Runtime control authors because you will have a peer instance available at run time, after the runtime invokes the OnCreateAutomationPeer method. Using this peer, you can fire automation events by calling RaiseAutomationEvent and RaisePropertyChangedEvent. You would do this whenever a related property in the peer's owner (your class) changes, or when firing an event is needed for correct automation support.

The automation support design doesn't retain a handle to your own peer as part of how you implement OnCreateAutomationPeer, because there aren't any guarantees of when the peer is actually created. Instead, you can check for run-time automation event listeners inside your control class definitions just-in-time, using code like this:

if (AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged))
{
    MyAutomationPeer peer = 
        FrameworkElementAutomationPeer.FromElement(myCtrl) as MyAutomationPeer;

    if (peer != null)
    {
        peer.RaisePropertyChangedEvent(
            RangeValuePatternIdentifiers.ValueProperty,
            (double)oldValue,
            (double)newValue);
    }
}

AutomationPeer derived classes

AutomationPeer is in the hierarchy for all the existing peers for the Windows Runtime controls and related UI classes.

Classes that directly derive from AutomationPeer are:

FrameworkElementAutomationPeer. For a list of the peers that derive from FrameworkElementAutomationPeer see Remarks section of FrameworkElementAutomationPeer.

Core methods

The "Core" methods are the standard implementations that perform the default action of an associated Microsoft UI Automation client-callable method. You can override any of the "Core" methods to return alternative values in a custom automation peer. For example, GetAcceleratorKeyCore is invoked any time that GetAcceleratorKey is called, GetAccessKeyCore is invoked any time that GetAccessKey is called, and so on.

The base implementation for AutomationPeer returns null. Peers that represent items may defer the result to their container.

Constructors

AutomationPeer()

Provides base class initialization behavior for AutomationPeer derived classes.

Properties

Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
EventsSource	Gets or sets an AutomationPeer that is reported to the automation client as the source for all the events that come from this AutomationPeer. See Remarks.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GenerateRawElementProviderRuntimeId()	Generates a runtime identifier for the element that is associated with the automation peer.
GetAcceleratorKey()	Gets the accelerator key combinations for the object that is associated with the UI Automation peer.
GetAcceleratorKeyCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetAcceleratorKey or an equivalent Microsoft UI Automation client API.
GetAccessKey()	Gets the access key for the element that is associated with the automation peer.
GetAccessKeyCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetAccessKey or an equivalent Microsoft UI Automation client API.
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetAnnotations()	Gets a reference to the list of UI automation annotations for the current automation peer.
GetAnnotationsCore()	Provides the behavior of the peer when a Microsoft UI Automation client calls GetAnnotations or an equivalent Microsoft UI Automation client API.
GetAutomationControlType()	Gets the control type for the element that is associated with the UI Automation peer.
GetAutomationControlTypeCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetAutomationControlType or an equivalent Microsoft UI Automation client API.
GetAutomationId()	Gets the AutomationId of the element that is associated with the automation peer.
GetAutomationIdCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetAutomationId or an equivalent Microsoft UI Automation client API.
GetBoundingRectangle()	Gets the Rect object that represents the screen coordinates of the element that is associated with the automation peer.
GetBoundingRectangleCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetBoundingRectangle or an equivalent Microsoft UI Automation client API.
GetChildren()	Gets the collection of child elements that are represented in the UI Automation tree as immediate child elements of the automation peer.
GetChildrenCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetChildren or an equivalent Microsoft UI Automation client API.
GetClassName()	Gets a name that is used with AutomationControlType, to differentiate the control that is represented by this AutomationPeer.
GetClassNameCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetClassName or an equivalent Microsoft UI Automation client API.
GetClickablePoint()	Gets a point on the element that is associated with the automation peer that responds to a mouse click.
GetClickablePointCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetClickablePoint or an equivalent Microsoft UI Automation client API.
GetControlledPeers()	Provides the peer's behavior when a Microsoft UI Automation client calls GetControlledPeers or an equivalent Microsoft UI Automation client API such as getting a property value as identified by UIA_ControllerForPropertyId.
GetControlledPeersCore()	Gets a list of the controlled peers for the current automation peer.
GetCulture()	Calls GetCultureCore to get the culture value for the element that is associated with the automation peer.
GetCultureCore()	Gets the culture value for the element that is associated with the automation peer.
GetDescribedByCore()	Gets a collection of elements that provide more information about the automation element.
GetElementFromPoint(Point)	Gets an element from the specified point.
GetElementFromPointCore(Point)	Provides the behavior of the peer when a Microsoft UI Automation client calls GetElementFromPoint or an equivalent Microsoft UI Automation client API.
GetFlowsFromCore()	Provides the peer's behavior when a Microsoft UI Automation client calls AutomationProperties.GetFlowsFrom or an equivalent Microsoft UI Automation client API.
GetFlowsToCore()	Provides the peer's behavior when a Microsoft UI Automation client calls AutomationProperties.GetFlowsTo or an equivalent Microsoft UI Automation client API.
GetFocusedElement()	Gets the element that currently has the focus.
GetFocusedElementCore()	Provides the behavior of the peer when a Microsoft UI Automation client calls GetFocusedElement or an equivalent Microsoft UI Automation client API.
GetFullDescription()	Gets a localized string that describes the actual visual appearance or contents of something such as an image or image control.
GetFullDescriptionCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetFullDescription or an equivalent Microsoft UI Automation client API.
GetHeadingLevel()	Gets the heading level of the UI Automation element that is associated with this automation peer.
GetHeadingLevelCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetHeadingLevel or an equivalent Microsoft UI Automation client API.
GetHelpText()	Gets text that describes the functionality of the control that is associated with the automation peer.
GetHelpTextCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetHelpText or an equivalent Microsoft UI Automation client API.
GetItemStatus()	Gets text that conveys the visual status of the element that is associated with this automation peer.
GetItemStatusCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetItemStatus or an equivalent Microsoft UI Automation client API.
GetItemType()	Gets a string that describes what kind of item an element represents.
GetItemTypeCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetItemType or an equivalent Microsoft UI Automation client API.
GetLabeledBy()	Gets the AutomationPeer for the UIElement that is targeted to the element.
GetLabeledByCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetLabeledBy or an equivalent Microsoft UI Automation client API.
GetLandmarkType()	Gets the landmark type for this automation peer.
GetLandmarkTypeCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetLandmarkType or an equivalent Microsoft UI Automation client API.
GetLevel()	Returns the 1-based integer for the level (hierarchy) of the element that is associated with the automation peer.
GetLevelCore()	Provides the behavior of the peer when a Microsoft UI Automation client calls GetLevel or an equivalent Microsoft UI Automation client API.
GetLiveSetting()	Gets the live setting notification behavior information for the object that is associated with the UI Automation peer.
GetLiveSettingCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetLiveSetting or an equivalent Microsoft UI Automation client API.
GetLocalizedControlType()	Gets a localized string that represents the AutomationControlType value for the control that is associated with this automation peer.
GetLocalizedControlTypeCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetLocalizedControlType or an equivalent Microsoft UI Automation client API.
GetLocalizedLandmarkType()	Gets a localized string that represents the AutomationLandmarkType value for the element that is associated with this automation peer.
GetLocalizedLandmarkTypeCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetLocalizedLandmarkType or an equivalent Microsoft UI Automation client API.
GetName()	Gets text that describes the element that is associated with this automation peer. The Microsoft UI Automation Name value is the primary identifier used by most assistive technology when they represent your app's UI by interacting with the Microsoft UI Automation framework.
GetNameCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetName or an equivalent Microsoft UI Automation client API.
GetOrientation()	Gets a value that indicates the explicit control orientation, if any.
GetOrientationCore()	Provides the peer's behavior when a Microsoft UI Automation client calls GetOrientation or an equivalent Microsoft UI Automation client API.
GetParent()	Gets the AutomationPeer that is the parent of this AutomationPeer.
GetPattern(PatternInterface)	Gets the control pattern that is associated with the specified PatternInterface.
GetPatternCore(PatternInterface)	Provides the peer's behavior when a Microsoft UI Automation client calls GetPattern or an equivalent Microsoft UI Automation client API.
GetPeerFromPoint(Point)	Gets an AutomationPeer from the specified point.
GetPeerFromPointCore(Point)	Provides the peer's behavior when a Microsoft UI Automation client calls GetPeerFromPoint or an equivalent Microsoft UI Automation client API.
GetPositionInSet()	Returns the 1-based integer for the ordinal position in the set for the element that is associated with the automation peer.
GetPositionInSetCore()	Provides the peer’s behavior when a Microsoft UI Automation client calls GetPositionInSet or an equivalent Microsoft UI Automation client API.
GetSizeOfSet()	Returns the 1-based integer for the size of the set where the element that is associated with the automation peer is located.
GetSizeOfSetCore()	Provides the peer’s behavior when a Microsoft UI Automation client calls GetSizeOfSet or an equivalent Microsoft UI Automation client API.
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
HasKeyboardFocus()	Gets a value that indicates whether the element that is associated with this automation peer currently has keyboard focus.
HasKeyboardFocusCore()	Provides the peer's behavior when a Microsoft UI Automation client calls HasKeyboardFocus or an equivalent Microsoft UI Automation client API.
InvalidatePeer()	Triggers recalculation of the main properties of the AutomationPeer and raises the PropertyChanged notification to the automation client if the properties have changed.
IsContentElement()	Gets a value that indicates whether the element that is associated with this automation peer contains data that is presented to the user.
IsContentElementCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsContentElement or an equivalent Microsoft UI Automation client API.
IsControlElement()	Gets a value that indicates whether the element is understood by the user as interactive or as contributing to the logical structure of the control in the GUI.
IsControlElementCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsControlElement or an equivalent Microsoft UI Automation client API.
IsDataValidForForm()	Gets a Boolean value that indicates whether the entered or selected value is valid for the form rule associated with the automation element.
IsDataValidForFormCore()	Provides the peer’s behavior when a Microsoft UI Automation client accesses IsDataValidForForm or an equivalent Microsoft UI Automation client API.
IsDialog()	Gets a value that indicates whether the element associated with this automation peer is a dialog window.
IsDialogCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsDialog or an equivalent Microsoft UI Automation client API.
IsEnabled()	Gets a value that indicates whether the element associated with this automation peer supports interaction.
IsEnabledCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsEnabled or an equivalent Microsoft UI Automation client API.
IsKeyboardFocusable()	Gets a value that indicates whether the element can accept keyboard focus.
IsKeyboardFocusableCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsKeyboardFocusable or an equivalent Microsoft UI Automation client API.
IsOffscreen()	Gets a value that indicates whether an element is off the screen.
IsOffscreenCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsOffscreen or an equivalent Microsoft UI Automation client API.
IsPassword()	Gets a value that indicates whether the element contains sensitive content.
IsPasswordCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsPassword or an equivalent Microsoft UI Automation client API.
IsPeripheral()	Gets a Boolean value that indicates whether the automation element represents peripheral UI.
IsPeripheralCore()	Provides the peer’s behavior when a Microsoft UI Automation client accesses IsPeripheral or an equivalent Microsoft UI Automation client API.
IsRequiredForForm()	Gets a value that indicates whether the element that is associated with this peer must be completed on a form.
IsRequiredForFormCore()	Provides the peer's behavior when a Microsoft UI Automation client calls IsRequiredForForm or an equivalent Microsoft UI Automation client API.
ListenerExists(AutomationEvents)	Gets a value that indicates whether Microsoft UI Automation reports that a client is listening for the specified event.
Navigate(AutomationNavigationDirection)	Gets the element in the specified direction within the UI automation tree.
NavigateCore(AutomationNavigationDirection)	Provides the peer’s behavior when a Microsoft UI Automation client calls Navigate or an equivalent Microsoft UI Automation client API.
PeerFromProvider(IRawElementProviderSimple)	Gets an AutomationPeer for the specified IRawElementProviderSimple proxy.
ProviderFromPeer(AutomationPeer)	Gets the IRawElementProviderSimple proxy for the specified AutomationPeer.
RaiseAutomationEvent(AutomationEvents)	Raises an automation event.
RaiseNotificationEvent(AutomationNotificationKind, AutomationNotificationProcessing, String, String)	Initiates a notification event.
RaisePropertyChangedEvent(AutomationProperty, Object, Object)	Raises an event to notify the automation client of a changed property value.
RaiseStructureChangedEvent(AutomationStructureChangeType, AutomationPeer)	Raises an event to notify the Microsoft UI Automation core that the tree structure has changed.
RaiseTextEditTextChangedEvent(AutomationTextEditChangeType, IVectorView<String>)	Raises an event to notify the Microsoft UI Automation core that a text control has programmatically changed text.
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetFocus()	Sets the keyboard focus on the element that is associated with this automation peer.
SetFocusCore()	Provides the peer's behavior when a Microsoft UI Automation client calls SetFocus or an equivalent Microsoft UI Automation client API.
SetParent(AutomationPeer)	Sets the AutomationPeer that is the parent of this AutomationPeer.
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
ShowContextMenu()	Shows the available context menu for the owner element.
ShowContextMenuCore()	Provides the peer's behavior when a Microsoft UI Automation client calls ShowContextMenu or an equivalent Microsoft UI Automation client API.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to

Share via