AutomationPeer AutomationPeer AutomationPeer Class

Definition

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

public : class AutomationPeer : DependencyObject, IAutomationPeer, IAutomationPeer2, IAutomationPeer3, IAutomationPeer4, IAutomationPeer5, IAutomationPeer6, IAutomationPeerOverrides, IAutomationPeerOverrides2, IAutomationPeerOverrides3, IAutomationPeerOverrides4, IAutomationPeerOverrides5, IAutomationPeerOverrides6, IAutomationPeerProtected
public class AutomationPeer : DependencyObject, IAutomationPeer, IAutomationPeer2, IAutomationPeer3, IAutomationPeer4, IAutomationPeer5, IAutomationPeer6, IAutomationPeerOverrides, IAutomationPeerOverrides2, IAutomationPeerOverrides3, IAutomationPeerOverrides4, IAutomationPeerOverrides5, IAutomationPeerOverrides6, IAutomationPeerProtected
Public Class AutomationPeer Inherits DependencyObject Implements IAutomationPeer, IAutomationPeer2, IAutomationPeer3, IAutomationPeer4, IAutomationPeer5, IAutomationPeer6, IAutomationPeerOverrides, IAutomationPeerOverrides2, IAutomationPeerOverrides3, IAutomationPeerOverrides4, IAutomationPeerOverrides5, IAutomationPeerOverrides6, IAutomationPeerProtected
Inheritance
AutomationPeerAutomationPeerAutomationPeer
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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);
    }
}
If AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged) Then
    Dim peer As MyAutomationPeer = _
    TryCast(FrameworkElementAutomationPeer.FromElement(myCtrl), MyAutomationPeer)
    If peer IsNot Nothing Then
        peer.RaisePropertyChangedEvent(RangeValuePatternIdentifiers.ValueProperty, CDbl(oldValue), CDbl(newValue))
    End If
End If

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:

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() AutomationPeer() AutomationPeer()

Provides base class initialization behavior for AutomationPeer derived classes.

protected : AutomationPeer()
protected AutomationPeer()
Protected Sub New()

Properties

Dispatcher Dispatcher Dispatcher

Inherited from DependencyObject

EventsSource EventsSource 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.

public : AutomationPeer EventsSource { get; set; }
public AutomationPeer EventsSource { get; set; }
Public ReadWrite Property EventsSource As AutomationPeer
Value
AutomationPeer AutomationPeer AutomationPeer

The AutomationPeer that is the source of events.

Remarks

EventsSource is typically set by AutomationPeer implementations in cases where the automation provider element is a child element of another element that also has a peer, and the best automation experience for clients is to treat the parent as the source for automation events. In such cases, the child element's peer implementation sets EventsSource to return the AutomationPeer of the parent element.

Methods

ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Inherited from DependencyObject

GenerateRawElementProviderRuntimeId() GenerateRawElementProviderRuntimeId() GenerateRawElementProviderRuntimeId()

Generates a runtime identifier for the element that is associated with the automation peer.

public : static RawElementProviderRuntimeId GenerateRawElementProviderRuntimeId()
public static RawElementProviderRuntimeId GenerateRawElementProviderRuntimeId()
Public Static Function GenerateRawElementProviderRuntimeId() As RawElementProviderRuntimeId
Returns

GetAcceleratorKey() GetAcceleratorKey() GetAcceleratorKey()

Gets the accelerator key combinations for the object that is associated with the UI Automation peer.

public : Platform::String GetAcceleratorKey()
public string GetAcceleratorKey()
Public Function GetAcceleratorKey() As string
Returns
Platform::String string string

The accelerator key.

GetAcceleratorKeyCore() GetAcceleratorKeyCore() GetAcceleratorKeyCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetAcceleratorKey or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetAcceleratorKeyCore()
protected virtual string GetAcceleratorKeyCore()
Protected Overridable Function GetAcceleratorKeyCore() As string
Returns
Platform::String string string

The accelerator key.

See Also

GetAccessKey() GetAccessKey() GetAccessKey()

Gets the access key for the element that is associated with the automation peer.

public : Platform::String GetAccessKey()
public string GetAccessKey()
Public Function GetAccessKey() As string
Returns
Platform::String string string

The access key.

GetAccessKeyCore() GetAccessKeyCore() GetAccessKeyCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetAccessKey or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetAccessKeyCore()
protected virtual string GetAccessKeyCore()
Protected Overridable Function GetAccessKeyCore() As string
Returns
Platform::String string string

The access key.

See Also

GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty)

Inherited from DependencyObject

GetAnnotations() GetAnnotations() GetAnnotations()

Gets a reference to the list of UI automation annotations for the current automation peer.

public : IVector<AutomationPeerAnnotation> GetAnnotations()
public IList<AutomationPeerAnnotation> GetAnnotations()
Public Function GetAnnotations() As IList<AutomationPeerAnnotation>( Of AutomationPeerAnnotation )
Returns
IVector<AutomationPeerAnnotation> IList<AutomationPeerAnnotation> IList<AutomationPeerAnnotation>

The list of UI automation annotations.

GetAnnotationsCore() GetAnnotationsCore() GetAnnotationsCore()

Provides the behavior of the peer when a Microsoft UI Automation client calls GetAnnotations or an equivalent Microsoft UI Automation client API.

protected : virtual IVector<AutomationPeerAnnotation> GetAnnotationsCore()
protected virtual IList<AutomationPeerAnnotation> GetAnnotationsCore()
Protected Overridable Function GetAnnotationsCore() As IList<AutomationPeerAnnotation>( Of AutomationPeerAnnotation )
Returns
IVector<AutomationPeerAnnotation> IList<AutomationPeerAnnotation> IList<AutomationPeerAnnotation>

The behavior of the peer.

GetAutomationControlType() GetAutomationControlType() GetAutomationControlType()

Gets the control type for the element that is associated with the UI Automation peer.

public : AutomationControlType GetAutomationControlType()
public AutomationControlType GetAutomationControlType()
Public Function GetAutomationControlType() As AutomationControlType
Returns

GetAutomationControlTypeCore() GetAutomationControlTypeCore() GetAutomationControlTypeCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetAutomationControlType or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationControlType GetAutomationControlTypeCore()
protected virtual AutomationControlType GetAutomationControlTypeCore()
Protected Overridable Function GetAutomationControlTypeCore() As AutomationControlType
Returns

Remarks

The base implementation for AutomationPeer and FrameworkElementAutomationPeer return Custom. If you keep this behavior, you must override GetLocalizedControlTypeCore.

The more common scenario for defining an automation peer is overriding one of the existing peer classes that pairs with the control class you are overriding. In this case each such peer class reports a practical value of AutomationControlType that makes sense for the original owner control that the peer was implemented for. Often you can leave this behavior alone. It isn't typical to derive from a control-specific peer and use its behavior but then change the AutomationControlType, which is probably the most basic information that a peer reports. Check the existing behavior of the peer class you are overriding, and verify that you're reporting the correct control type. Also, double-check that there isn't a more specific peer class available that could already be reporting the correct control type as well as providing other behavior that's more appropriate for your peer. For more info, see Custom automation peers.

See Also

GetAutomationId() GetAutomationId() GetAutomationId()

Gets the AutomationId of the element that is associated with the automation peer.

public : Platform::String GetAutomationId()
public string GetAutomationId()
Public Function GetAutomationId() As string
Returns
Platform::String string string

The automation identifier.

GetAutomationIdCore() GetAutomationIdCore() GetAutomationIdCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetAutomationId or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetAutomationIdCore()
protected virtual string GetAutomationIdCore()
Protected Overridable Function GetAutomationIdCore() As string
Returns
Platform::String string string

The automation identifier.

Remarks

Providing a class-based behavior for AutomationId is uncommon. Typically, app authors set values for elements in the app by setting the AutomationProperties.AutomationId attached property in the XAML UI definition.

See Also

GetBoundingRectangle() GetBoundingRectangle() GetBoundingRectangle()

Gets the Rect object that represents the screen coordinates of the element that is associated with the automation peer.

public : Rect GetBoundingRectangle()
public Rect GetBoundingRectangle()
Public Function GetBoundingRectangle() As Rect
Returns

The bounding rectangle.

See Also

GetBoundingRectangleCore() GetBoundingRectangleCore() GetBoundingRectangleCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetBoundingRectangle or an equivalent Microsoft UI Automation client API.

protected : virtual Rect GetBoundingRectangleCore()
protected virtual Rect GetBoundingRectangleCore()
Protected Overridable Function GetBoundingRectangleCore() As Rect
Returns

The bounding rectangle.

See Also

GetChildren() GetChildren() GetChildren()

Gets the collection of child elements that are represented in the UI Automation tree as immediate child elements of the automation peer.

public : IVector<AutomationPeer> GetChildren()
public IList<AutomationPeer> GetChildren()
Public Function GetChildren() As IList<AutomationPeer>( Of AutomationPeer )
Returns
IVector<AutomationPeer> IList<AutomationPeer> IList<AutomationPeer>

The collection of AutomationPeer objects for child elements.

GetChildrenCore() GetChildrenCore() GetChildrenCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetChildren or an equivalent Microsoft UI Automation client API.

protected : virtual IVector<AutomationPeer> GetChildrenCore()
protected virtual IList<AutomationPeer> GetChildrenCore()
Protected Overridable Function GetChildrenCore() As IList<AutomationPeer>( Of AutomationPeer )
Returns
IVector<AutomationPeer> IList<AutomationPeer> IList<AutomationPeer>

The collection of AutomationPeer objects for child elements.

Remarks

The base implementation returns null. Peers that represent controls with item collections may override this result. Test the behavior of the peer you are using or overriding and override GetChildrenCore if you want to change that behavior.

See Also

GetClassName() GetClassName() GetClassName()

Gets a name that is used with AutomationControlType, to differentiate the control that is represented by this AutomationPeer.

public : Platform::String GetClassName()
public string GetClassName()
Public Function GetClassName() As string
Returns
Platform::String string string

The class name.

GetClassNameCore() GetClassNameCore() GetClassNameCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetClassName or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetClassNameCore()
protected virtual string GetClassNameCore()
Protected Overridable Function GetClassNameCore() As string
Returns
Platform::String string string

The class name.

Remarks

You should never invoke the base behavior, and all custom peers should override GetClassNameCore to report the class name that is unique to that peer class. For more info, see Custom automation peers.

See Also

GetClickablePoint() GetClickablePoint() GetClickablePoint()

Gets a point on the element that is associated with the automation peer that responds to a mouse click.

public : Point GetClickablePoint()
public Point GetClickablePoint()
Public Function GetClickablePoint() As Point
Returns

A point in the clickable area of the element.

GetClickablePointCore() GetClickablePointCore() GetClickablePointCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetClickablePoint or an equivalent Microsoft UI Automation client API.

protected : virtual Point GetClickablePointCore()
protected virtual Point GetClickablePointCore()
Protected Overridable Function GetClickablePointCore() As Point
Returns

A point within the clickable area of the element.

Remarks

The base implementation returns a default Point (coordinates 0,0). Peers that represent items defer to the container. ScrollBarAutomationPeer and SliderAutomationPeer both have behavior that can't adequately express one point for the purposes of GetClickablePoint scenarios, so these return a Point where the coordinate values are Double.NaN.

Note

Visual C++ component extensions (C++/CX) doesn't have a constant for NaN, it uses a value, which appears as "-1.#IND" followed by zeros. Automation clients using languages other than C# or Visual C++ component extensions (C++/CX) may see NaN represented in a different form.

See Also

GetControlledPeers() GetControlledPeers() 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.

public : IVectorView<AutomationPeer> GetControlledPeers()
public IReadOnlyList<AutomationPeer> GetControlledPeers()
Public Function GetControlledPeers() As IReadOnlyList<AutomationPeer>( Of AutomationPeer )
Returns
IVectorView<AutomationPeer> IReadOnlyList<AutomationPeer> IReadOnlyList<AutomationPeer>

A list of the controlled peers for the current automation peer.

Remarks

Examining controlled peers is an advanced scenario that most peer implementations won't need to use.

The naming of the framework implementation and the Microsoft UI Automation property that clients can use to access this info are slightly different. Microsoft UI Automation clients should use the identifier UIA_ControllerForPropertyId to request the value of this property when using the Microsoft UI Automation client interfaces such as IUIAutomation.

GetControlledPeersCore() GetControlledPeersCore() GetControlledPeersCore()

Gets a list of the controlled peers for the current automation peer.

protected : virtual IVectorView<AutomationPeer> GetControlledPeersCore()
protected virtual IReadOnlyList<AutomationPeer> GetControlledPeersCore()
Protected Overridable Function GetControlledPeersCore() As IReadOnlyList<AutomationPeer>( Of AutomationPeer )
Returns
IVectorView<AutomationPeer> IReadOnlyList<AutomationPeer> IReadOnlyList<AutomationPeer>

A list of the controlled peers for the current automation peer.

Remarks

Examining controlled peers is an advanced scenario that most peer implementations won't need to use.

GetCulture() GetCulture() GetCulture()

Calls GetCultureCore to get the culture value for the element that is associated with the automation peer.

public : int GetCulture()
public int GetCulture()
Public Function GetCulture() As int
Returns
int int int

The value of the culture property for the element that is associated with the automation peer.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

GetCultureCore() GetCultureCore() GetCultureCore()

Gets the culture value for the element that is associated with the automation peer.

protected : virtual int GetCultureCore()
protected virtual int GetCultureCore()
Protected Overridable Function GetCultureCore() As int
Returns
int int int

The value of the culture property for the element that is associated with the automation peer.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

GetDescribedByCore() GetDescribedByCore() GetDescribedByCore()

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

protected : virtual IIterable<AutomationPeer> GetDescribedByCore()
protected virtual IEnumerable<AutomationPeer> GetDescribedByCore()
Protected Overridable Function GetDescribedByCore() As IEnumerable<AutomationPeer>( Of AutomationPeer )
Returns
IIterable<AutomationPeer> IEnumerable<AutomationPeer> IEnumerable<AutomationPeer>

A collection of elements that provide more information about the automation element.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

GetDescribedBy is used when an automation element is explained by another segment of the application UI. For example, the collection can point to a text element of "2,529 items in 85 groups, 10 items selected" from a complex custom list object. Instead of using the object model for clients to digest similar information, the collection returned by GetDescribedBy can offer quick access to UI elements that may already offer useful end-user information that describes the UI element.

GetElementFromPoint(Point) GetElementFromPoint(Point) GetElementFromPoint(Point)

Gets an element from the specified point.

public : Platform::Object GetElementFromPoint(Point pointInWindowCoordinates)
public object GetElementFromPoint(Point pointInWindowCoordinates)
Public Function GetElementFromPoint(pointInWindowCoordinates As Point) As object
Parameters
pointInWindowCoordinates
Point Point Point

The specified point.

Returns
Platform::Object object object

The element at the specified point.

GetElementFromPointCore(Point) GetElementFromPointCore(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.

protected : virtual Platform::Object GetElementFromPointCore(Point pointInWindowCoordinates)
protected virtual object GetElementFromPointCore(Point pointInWindowCoordinates)
Protected Overridable Function GetElementFromPointCore(pointInWindowCoordinates As Point) As object
Parameters
pointInWindowCoordinates
Point Point Point

The specified point.

Returns
Platform::Object object object

The behavior of the peer.

GetFlowsFromCore() GetFlowsFromCore() GetFlowsFromCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetFlowsFrom or an equivalent Microsoft UI Automation client API.

protected : virtual IIterable<AutomationPeer> GetFlowsFromCore()
protected virtual IEnumerable<AutomationPeer> GetFlowsFromCore()
Protected Overridable Function GetFlowsFromCore() As IEnumerable<AutomationPeer>( Of AutomationPeer )
Returns
IIterable<AutomationPeer> IEnumerable<AutomationPeer> IEnumerable<AutomationPeer>

A list of automation elements that suggests the reading order before the current automation element.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

The "Core" methods are the standard implementations that perform the default action of an associated UI Automation client-callable method. You can override any of the "Core" methods to return alternative values in a custom automation peer. In this case, GetFlowsFromCore is invoked any time that GetFlowsFrom is called.

The base implementation for AutomationPeer returns null.

GetFlowsToCore() GetFlowsToCore() GetFlowsToCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetFlowsTo or an equivalent Microsoft UI Automation client API.

protected : virtual IIterable<AutomationPeer> GetFlowsToCore()
protected virtual IEnumerable<AutomationPeer> GetFlowsToCore()
Protected Overridable Function GetFlowsToCore() As IEnumerable<AutomationPeer>( Of AutomationPeer )
Returns
IIterable<AutomationPeer> IEnumerable<AutomationPeer> IEnumerable<AutomationPeer>

A list of automation elements that suggests the reading order after the current automation element.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

The "Core" methods are the standard implementations that perform the default action of an associated UI Automation client-callable method. You can override any of the "Core" methods to return alternative values in a custom automation peer. In this case, GetFlowsToCore is invoked any time that GetFlowsTo is called.

The base implementation for AutomationPeer returns null.

GetFocusedElement() GetFocusedElement() GetFocusedElement()

Gets the element that currently has the focus.

public : Platform::Object GetFocusedElement()
public object GetFocusedElement()
Public Function GetFocusedElement() As object
Returns
Platform::Object object object

The element that currently has the focus.

GetFocusedElementCore() GetFocusedElementCore() GetFocusedElementCore()

Provides the behavior of the peer when a Microsoft UI Automation client calls GetFocusedElement or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Object GetFocusedElementCore()
protected virtual object GetFocusedElementCore()
Protected Overridable Function GetFocusedElementCore() As object
Returns
Platform::Object object object

The behavior of the peer.

GetFullDescription() GetFullDescription() GetFullDescription()

Gets a localized string that describes the actual visual appearance or contents of something such as an image or image control.

public : Platform::String GetFullDescription()
public string GetFullDescription()
Public Function GetFullDescription() As string
Returns
Platform::String string string

A localized string that describes the actual visual appearance or contents of something such as an image or image control.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

GetFullDescriptionCore() GetFullDescriptionCore() GetFullDescriptionCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetFullDescription or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetFullDescriptionCore()
protected virtual string GetFullDescriptionCore()
Protected Overridable Function GetFullDescriptionCore() As string
Returns
Platform::String string string

A localized string that describes the actual visual appearance or contents of something such as an image or image control.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

You should never invoke the base behavior, and all custom peers should override GetFullDescriptionCore to report the full description of this AutomationPeer. For more info, see Custom automation peers.

GetHelpText() GetHelpText() GetHelpText()

Gets text that describes the functionality of the control that is associated with the automation peer.

public : Platform::String GetHelpText()
public string GetHelpText()
Public Function GetHelpText() As string
Returns
Platform::String string string

The help text.

GetHelpTextCore() GetHelpTextCore() GetHelpTextCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetHelpText or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetHelpTextCore()
protected virtual string GetHelpTextCore()
Protected Overridable Function GetHelpTextCore() As string
Returns
Platform::String string string

The help text.

Remarks

Specifying a control behavior for help text is uncommon. In most cases, apps that need it will establish help text information in the UI by applying the AutomationProperties.HelpText attached property to the UI definition XAML.

See Also

GetItemStatus() GetItemStatus() GetItemStatus()

Gets text that conveys the visual status of the element that is associated with this automation peer.

public : Platform::String GetItemStatus()
public string GetItemStatus()
Public Function GetItemStatus() As string
Returns
Platform::String string string

The item status.

GetItemStatusCore() GetItemStatusCore() GetItemStatusCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetItemStatus or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetItemStatusCore()
protected virtual string GetItemStatusCore()
Protected Overridable Function GetItemStatusCore() As string
Returns
Platform::String string string

The item status.

See Also

GetItemType() GetItemType() GetItemType()

Gets a string that describes what kind of item an element represents.

public : Platform::String GetItemType()
public string GetItemType()
Public Function GetItemType() As string
Returns
Platform::String string string

The kind of item.

GetItemTypeCore() GetItemTypeCore() GetItemTypeCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetItemType or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetItemTypeCore()
protected virtual string GetItemTypeCore()
Protected Overridable Function GetItemTypeCore() As string
Returns
Platform::String string string

The kind of item.

See Also

GetLabeledBy() GetLabeledBy() GetLabeledBy()

Gets the AutomationPeer for the UIElement that is targeted to the element.

public : AutomationPeer GetLabeledBy()
public AutomationPeer GetLabeledBy()
Public Function GetLabeledBy() As AutomationPeer
Returns

The AutomationPeer for the element that is targeted by the UIElement.

GetLabeledByCore() GetLabeledByCore() GetLabeledByCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetLabeledBy or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationPeer GetLabeledByCore()
protected virtual AutomationPeer GetLabeledByCore()
Protected Overridable Function GetLabeledByCore() As AutomationPeer
Returns

The AutomationPeer for the element that is targeted by the UIElement.

Remarks

Specifying a control behavior for labeling is uncommon except for composite data presentation controls that use headers or similar metaphors. In most cases apps establish labeling information between the elements in an app-specific UI by applying the AutomationProperties.LabeledBy attached property to the UI definition XAML.

See Also

GetLandmarkType() GetLandmarkType() GetLandmarkType()

Gets the landmark type for this automation peer.

public : AutomationLandmarkType GetLandmarkType()
public AutomationLandmarkType GetLandmarkType()
Public Function GetLandmarkType() As AutomationLandmarkType
Returns

The landmark type for this automation peer.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

GetLandmarkTypeCore() GetLandmarkTypeCore() GetLandmarkTypeCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetLandmarkType or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationLandmarkType GetLandmarkTypeCore()
protected virtual AutomationLandmarkType GetLandmarkTypeCore()
Protected Overridable Function GetLandmarkTypeCore() As AutomationLandmarkType
Returns
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

GetLevel() GetLevel() GetLevel()

Returns the 1-based integer for the level (hierarchy) of the element that is associated with the automation peer.

public : int GetLevel()
public int GetLevel()
Public Function GetLevel() As int
Returns
int int int

The 1-based integer for the level of the element.

GetLevelCore() GetLevelCore() GetLevelCore()

Provides the behavior of the peer when a Microsoft UI Automation client calls GetLevel or an equivalent Microsoft UI Automation client API.

protected : virtual int GetLevelCore()
protected virtual int GetLevelCore()
Protected Overridable Function GetLevelCore() As int
Returns
int int int

The behavior of the peer.

GetLiveSetting() GetLiveSetting() GetLiveSetting()

Gets the live setting notification behavior information for the object that is associated with the UI Automation peer.

public : AutomationLiveSetting GetLiveSetting()
public AutomationLiveSetting GetLiveSetting()
Public Function GetLiveSetting() As AutomationLiveSetting
Returns

GetLiveSettingCore() GetLiveSettingCore() GetLiveSettingCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetLiveSetting or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationLiveSetting GetLiveSettingCore()
protected virtual AutomationLiveSetting GetLiveSettingCore()
Protected Overridable Function GetLiveSettingCore() As AutomationLiveSetting
Returns

A value of the enumeration that reports the live setting notification behavior for a peer implementation.

See Also

GetLocalizedControlType() GetLocalizedControlType() GetLocalizedControlType()

Gets a localized string that represents the AutomationControlType value for the control that is associated with this automation peer.

public : Platform::String GetLocalizedControlType()
public string GetLocalizedControlType()
Public Function GetLocalizedControlType() As string
Returns
Platform::String string string

The type of the control.

GetLocalizedControlTypeCore() GetLocalizedControlTypeCore() GetLocalizedControlTypeCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetLocalizedControlType or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetLocalizedControlTypeCore()
protected virtual string GetLocalizedControlTypeCore()
Protected Overridable Function GetLocalizedControlTypeCore() As string
Returns
Platform::String string string

The type of the control, as a string that is localized to be suitable for direct presentation to users by assistive technology.

Remarks

This method is very rarely overridden by peers. So long as you provide a value for GetAutomationControlTypeCore, all the enumerated constant names from AutomationControlType are already available in localized form to Microsoft UI Automation clients. The necessary translated strings are part of the Microsoft UI Automation support in every Microsoft Windows client. However, if you specify Custom as the control type, you must support a localized control type string that represents the role of the element (for example, "color picker" for a custom control that enables users to choose and specify colors).

See Also

GetLocalizedLandmarkType() GetLocalizedLandmarkType() GetLocalizedLandmarkType()

Gets a localized string that represents the AutomationLandmarkType value for the element that is associated with this automation peer.

public : Platform::String GetLocalizedLandmarkType()
public string GetLocalizedLandmarkType()
Public Function GetLocalizedLandmarkType() As string
Returns
Platform::String string string

The landmark type of the element.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

GetLocalizedLandmarkTypeCore() GetLocalizedLandmarkTypeCore() GetLocalizedLandmarkTypeCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetLocalizedLandmarkType or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetLocalizedLandmarkTypeCore()
protected virtual string GetLocalizedLandmarkTypeCore()
Protected Overridable Function GetLocalizedLandmarkTypeCore() As string
Returns
Platform::String string string

The landmark type of the peer, as a string that is localized to be suitable for direct presentation to users by assistive technology.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

GetName() GetName() 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.

public : Platform::String GetName()
public string GetName()
Public Function GetName() As string
Returns
Platform::String string string

The name of the element that is the peer's owner, as used by assistive technology and other Microsoft UI Automation clients.

Remarks

FrameworkElementAutomationPeer introduces behavior to GetName by providing an intermediate GetNameCore implementation. If an element has a value for the LabeledByMicrosoft UI Automation property, the labeling element's Name value is used as the Name.

FrameworkElementAutomationPeer also introduces behavior through an internal GetPlainText method that other default peer classes may override in order to access the content model of that control and return a useful default for Name. For example, any ContentControl derived class will use a string representation of its Content value as the default Name. This is enabled because internally ContentControl implements GetPlainText and imparts that behavior to all ContentControl derived classes. This is how you get a useful Name default from the string value of a Button, for example.

Other specific peers also may have an intermediate GetNameCore implementation that provides a useful way for that particular Windows Runtime control to provide built-in values for Name. The source of these values comes from other UI properties that are typically set in XAML or as app user code. For example, TextBoxAutomationPeer implements behavior that uses the value of the Text property from the owner TextBox as the default Name. From the user code perspective, the default behavior can be overridden by applying a different AutomationProperties.Name value. From the peer implementer / provider perspective, the default behavior of the peer can be changed by deriving a new peer class from the existing peer, overriding GetNameCore, and giving it a new implementation that wouldn't call the base implementation in at least some cases.

To learn more about the possible default behavior of specific peer classes for default Windows Runtime controls, see the reference topic for that particular peer class and look for implementation notes in the Remarks section.

See Also

GetNameCore() GetNameCore() GetNameCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetName or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::String GetNameCore()
protected virtual string GetNameCore()
Protected Overridable Function GetNameCore() As string
Returns
Platform::String string string

The name as used by assistive technology and other Microsoft UI Automation clients.

Remarks

FrameworkElementAutomationPeer introduces behavior to GetName by providing an intermediate GetNameCore implementation. If an element has a value for the LabeledByMicrosoft UI Automation property, the labeling element's Name value is used as the Name.

FrameworkElementAutomationPeer also introduces behavior through an internal GetPlainText method that other default peer classes may override in order to access the content model of that control and return a useful default for Name. For example, any ContentControl derived class will use a string representation of its Content value as the default Name. This is enabled because internally ContentControl implements GetPlainText and imparts that behavior to all ContentControl derived classes. This is how you get a useful Name default from the string value of a Button, for example.

Other specific peers also may have an intermediate GetNameCore implementation that provides a useful way for that particular Windows Runtime control to provide built-in values for Name. The source of these values comes from other UI properties that are typically set in XAML or as app user code. For example, TextBoxAutomationPeer implements behavior that uses the value of the Text property from the owner TextBox as the default Name. From the user code perspective, the default behavior can be overridden by applying a different AutomationProperties.Name value. From the peer implementer / provider perspective, the default behavior of the peer can be changed by deriving a new peer class from the existing peer, overriding GetNameCore, and giving it a new implementation that wouldn't call the base implementation in at least some cases.

To learn more about the possible default behavior of specific peer classes for default Windows Runtime controls, see the reference topic for that particular peer class and look for implementation notes in the Remarks section.

See Also

GetOrientation() GetOrientation() GetOrientation()

Gets a value that indicates the explicit control orientation, if any.

public : AutomationOrientation GetOrientation()
public AutomationOrientation GetOrientation()
Public Function GetOrientation() As AutomationOrientation
Returns

The orientation of the control as a value of the enumeration.

GetOrientationCore() GetOrientationCore() GetOrientationCore()

Provides the peer's behavior when a Microsoft UI Automation client calls GetOrientation or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationOrientation GetOrientationCore()
protected virtual AutomationOrientation GetOrientationCore()
Protected Overridable Function GetOrientationCore() As AutomationOrientation
Returns

Remarks

The base AutomationPeer implementation returns None. Peers that represent items may modify this to report information from their container. ScrollBarAutomationPeer and SliderAutomationPeer both have a pattern they can access that knows about orientation, so these peers can return a determined value. Test the existing return value in the peer that you are using or overriding and then override that behavior if necessary.

See Also

GetParent() GetParent() GetParent()

Gets the AutomationPeer that is the parent of this AutomationPeer.

public : AutomationPeer GetParent()
public AutomationPeer GetParent()
Public Function GetParent() As AutomationPeer
Returns

The parent automation peer.

GetPattern(PatternInterface) GetPattern(PatternInterface) GetPattern(PatternInterface)

Gets the control pattern that is associated with the specified PatternInterface.

public : Platform::Object GetPattern(PatternInterface patternInterface)
public object GetPattern(PatternInterface patternInterface)
Public Function GetPattern(patternInterface As PatternInterface) As object
Parameters
patternInterface
PatternInterface PatternInterface PatternInterface

A value from the PatternInterface enumeration.

Returns
Platform::Object object object

The object that implements the pattern interface; null if the peer does not support this interface.

GetPatternCore(PatternInterface) GetPatternCore(PatternInterface) GetPatternCore(PatternInterface)

Provides the peer's behavior when a Microsoft UI Automation client calls GetPattern or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Object GetPatternCore(PatternInterface patternInterface)
protected virtual object GetPatternCore(PatternInterface patternInterface)
Protected Overridable Function GetPatternCore(patternInterface As PatternInterface) As object
Parameters
patternInterface
PatternInterface PatternInterface PatternInterface

A value from the PatternInterface enumeration.

Returns
Platform::Object object object

The object that implements the pattern interface; null if the peer does not support this interface.

Remarks

The standard implementation at the AutomationPeer level returns null, because the basic peer class doesn't support any patterns. The majority of existing Windows Runtime peer classes override this method to report the patterns that a particular peer supports.

Overriding this method to return the implementation of patterns that your peer class supports is one of the most common scenarios for implementing an automation peer. You can see sample code for this in the XAML accessibility sample (Scenario 3). You should also read the Custom automation peers topic.

Windows 8 behavior

Windows 8 peer-selection behavior is potentially impacted by whether the control is intended to display data as items. The automation logic for Windows 8 might select a dedicated data peer and use its patterns, even if there is a peer indicated for the overall control and that peer overrides GetPatternCore. For example, you might have the ListViewAutomationPeer override for patterns, but in Windows 8 the acting patterns for data items might take precedence, for example the default implementation of ListViewItemDataAutomationPeer might be used and will handle the scrolling pattern when UI Automation looks for patterns in items. This is different starting with Windows 8.1; if there is pattern support indicated in a GetPatternCore implementation for the overall control, that implementation is used instead of internal item data peers.

If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it means that your items control pattern support may be used for data items too, and you might have to add behavior for item scrolling, for instance.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

See Also

GetPeerFromPoint(Point) GetPeerFromPoint(Point) GetPeerFromPoint(Point)

Gets an AutomationPeer from the specified point.

public : AutomationPeer GetPeerFromPoint(Point point)
public AutomationPeer GetPeerFromPoint(Point point)
Public Function GetPeerFromPoint(point As Point) As AutomationPeer
Parameters
point
Point Point Point

The relative position of the target UI element in the UI.

Returns

The AutomationPeer for the UI element at the specified point.

Remarks

This method is a utility for hit testing practical UI coordinates, evaluating the corresponding UI element, and returning the peer that corresponds to the hit-tested UI element.

GetPeerFromPointCore(Point) GetPeerFromPointCore(Point) GetPeerFromPointCore(Point)

Provides the peer's behavior when a Microsoft UI Automation client calls GetPeerFromPoint or an equivalent Microsoft UI Automation client API.

protected : virtual AutomationPeer GetPeerFromPointCore(Point point)
protected virtual AutomationPeer GetPeerFromPointCore(Point point)
Protected Overridable Function GetPeerFromPointCore(point As Point) As AutomationPeer
Parameters
point
Point Point Point

The relative position of the target UI element in the UI.

Returns

The AutomationPeer for the UI element at the specified point.

Remarks

Test the existing return value in the peer that you are using or overriding and then override that behavior if necessary.

See Also

GetPositionInSet() GetPositionInSet() GetPositionInSet()

Returns the 1-based integer for the ordinal position in the set for the element that is associated with the automation peer.

public : int GetPositionInSet()
public int GetPositionInSet()
Public Function GetPositionInSet() As int
Returns
int int int

The 1-based integer for the ordinal position in the set.

GetPositionInSetCore() GetPositionInSetCore() GetPositionInSetCore()

Provides the peer’s behavior when a Microsoft UI Automation client calls GetPositionInSet or an equivalent Microsoft UI Automation client API.

protected : virtual int GetPositionInSetCore()
protected virtual int GetPositionInSetCore()
Protected Overridable Function GetPositionInSetCore() As int
Returns
int int int

The peer’s behavior.

GetSizeOfSet() GetSizeOfSet() GetSizeOfSet()

Returns the 1-based integer for the size of the set where the element that is associated with the automation peer is located.

public : int GetSizeOfSet()
public int GetSizeOfSet()
Public Function GetSizeOfSet() As int
Returns
int int int

The 1-based integer for the size of the set.

GetSizeOfSetCore() GetSizeOfSetCore() GetSizeOfSetCore()

Provides the peer’s behavior when a Microsoft UI Automation client calls GetSizeOfSet or an equivalent Microsoft UI Automation client API.

protected : virtual int GetSizeOfSetCore()
protected virtual int GetSizeOfSetCore()
Protected Overridable Function GetSizeOfSetCore() As int
Returns
int int int

The peer’s behavior.

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Inherited from DependencyObject

HasKeyboardFocus() HasKeyboardFocus() HasKeyboardFocus()

Gets a value that indicates whether the element that is associated with this automation peer currently has keyboard focus.

public : Platform::Boolean HasKeyboardFocus()
public bool HasKeyboardFocus()
Public Function HasKeyboardFocus() As bool
Returns
Platform::Boolean bool bool

true if the element has keyboard focus; otherwise, false.

HasKeyboardFocusCore() HasKeyboardFocusCore() HasKeyboardFocusCore()

Provides the peer's behavior when a Microsoft UI Automation client calls HasKeyboardFocus or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean HasKeyboardFocusCore()
protected virtual bool HasKeyboardFocusCore()
Protected Overridable Function HasKeyboardFocusCore() As bool
Returns
Platform::Boolean bool bool

true if the element has keyboard focus; otherwise, false.

Remarks

The standard implementation at the AutomationPeer level checks whether the owner has focus, and always returns false if the owner isn't focusable. FrameworkElementAutomationPeer expands this behavior somewhat because it adds awareness of owner characteristics that rely on the owner being a Control subclass. Test the existing return value in the peer that you are using or overriding and then override that behavior if necessary.

See Also

InvalidatePeer() InvalidatePeer() InvalidatePeer()

Triggers recalculation of the main properties of the AutomationPeer and raises the PropertyChanged notification to the automation client if the properties have changed.

public : void InvalidatePeer()
public void InvalidatePeer()
Public Function InvalidatePeer() As void

IsContentElement() IsContentElement() IsContentElement()

Gets a value that indicates whether the element that is associated with this automation peer contains data that is presented to the user.

public : Platform::Boolean IsContentElement()
public bool IsContentElement()
Public Function IsContentElement() As bool
Returns
Platform::Boolean bool bool

true if the element is a content element; otherwise, false.

IsContentElementCore() IsContentElementCore() IsContentElementCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsContentElement or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsContentElementCore()
protected virtual bool IsContentElementCore()
Protected Overridable Function IsContentElementCore() As bool
Returns
Platform::Boolean bool bool

true if the element is a content element; otherwise, false.

Remarks

The standard implementation at the AutomationPeer level returns false. However, FrameworkElementAutomationPeer adds behavior that changes the default to true. Other specific peers also may affect this behavior; for example ItemAutomationPeer defers to its container. Test the existing return value in the peer that you are using or overriding and then override that behavior if necessary.

See Also

IsControlElement() IsControlElement() 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.

public : Platform::Boolean IsControlElement()
public bool IsControlElement()
Public Function IsControlElement() As bool
Returns
Platform::Boolean bool bool

true if the element is a control; otherwise, false.

IsControlElementCore() IsControlElementCore() IsControlElementCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsControlElement or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsControlElementCore()
protected virtual bool IsControlElementCore()
Protected Overridable Function IsControlElementCore() As bool
Returns
Platform::Boolean bool bool

true if the element is a control; otherwise, false.

Remarks

The standard implementation at the AutomationPeer level returns false. However, FrameworkElementAutomationPeer adds behavior that changes the default to true. Other specific peers also may affect this behavior; for example many peers return different values depending on whether the owner is created from a control template. Test the existing return value in the peer that you are using or overriding and then override that behavior if necessary.

See Also

IsDataValidForForm() IsDataValidForForm() IsDataValidForForm()

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

public : Platform::Boolean IsDataValidForForm()
public bool IsDataValidForForm()
Public Function IsDataValidForForm() As bool
Returns
Platform::Boolean bool bool

A Boolean value that indicates whether the entered or selected value is valid for the form rule associated with the automation element. The default return value is true.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

As an example, if the user entered "425-555-5555" for a zip code field that requires 5 or 9 digits, the IsDataValidForForm property can be set to false to indicate that the data is not valid.

IsDataValidForFormCore() IsDataValidForFormCore() IsDataValidForFormCore()

Provides the peer’s behavior when a Microsoft UI Automation client accesses IsDataValidForForm or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsDataValidForFormCore()
protected virtual bool IsDataValidForFormCore()
Protected Overridable Function IsDataValidForFormCore() As bool
Returns
Platform::Boolean bool bool

A Boolean value that indicates whether the entered or selected value is valid for the form rule associated with the automation element.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

IsEnabled() IsEnabled() IsEnabled()

Gets a value that indicates whether the element associated with this automation peer supports interaction.

public : Platform::Boolean IsEnabled()
public bool IsEnabled()
Public Function IsEnabled() As bool
Returns
Platform::Boolean bool bool

true if the element supports interaction; otherwise, false.

IsEnabledCore() IsEnabledCore() IsEnabledCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsEnabled or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsEnabledCore()
protected virtual bool IsEnabledCore()
Protected Overridable Function IsEnabledCore() As bool
Returns
Platform::Boolean bool bool

true if the element can be interacted with; otherwise, false.

Remarks

The standard implementation at the AutomationPeer level returns true. However, FrameworkElementAutomationPeer adds behavior that checks whether the owner is a Control and forwards owner information from Control.IsEnabled. For cases where the owner is not a control but does have a peer, such as for a TextBlock, the FrameworkElementAutomationPeer implementation returns true.

See Also

IsKeyboardFocusable() IsKeyboardFocusable() IsKeyboardFocusable()

Gets a value that indicates whether the element can accept keyboard focus.

public : Platform::Boolean IsKeyboardFocusable()
public bool IsKeyboardFocusable()
Public Function IsKeyboardFocusable() As bool
Returns
Platform::Boolean bool bool

true if the element can accept keyboard focus; otherwise, false.

IsKeyboardFocusableCore() IsKeyboardFocusableCore() IsKeyboardFocusableCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsKeyboardFocusable or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsKeyboardFocusableCore()
protected virtual bool IsKeyboardFocusableCore()
Protected Overridable Function IsKeyboardFocusableCore() As bool
Returns
Platform::Boolean bool bool

true if the element can accept keyboard focus; otherwise, false.

Remarks

The standard implementation at the AutomationPeer level returns false. However, FrameworkElementAutomationPeer adds behavior that checks whether the owner is a Control or otherwise focusable, and whether the owner is enabled.

See Also

IsOffscreen() IsOffscreen() IsOffscreen()

Gets a value that indicates whether an element is off the screen.

public : Platform::Boolean IsOffscreen()
public bool IsOffscreen()
Public Function IsOffscreen() As bool
Returns
Platform::Boolean bool bool

true if the element is not on the screen; otherwise, false.

IsOffscreenCore() IsOffscreenCore() IsOffscreenCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsOffscreen or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsOffscreenCore()
protected virtual bool IsOffscreenCore()
Protected Overridable Function IsOffscreenCore() As bool
Returns
Platform::Boolean bool bool

true if the element is not on the screen; otherwise, false.

Remarks

The standard implementation returns a result that is based on the owner's Visibility value.

See Also

IsPassword() IsPassword() IsPassword()

Gets a value that indicates whether the element contains sensitive content.

public : Platform::Boolean IsPassword()
public bool IsPassword()
Public Function IsPassword() As bool
Returns
Platform::Boolean bool bool

true if the element contains sensitive content such as a password; otherwise, false.

Remarks

This property enables applications such as screen readers to determine whether the text content of a control should be read aloud.

IsPasswordCore() IsPasswordCore() IsPasswordCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsPassword or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsPasswordCore()
protected virtual bool IsPasswordCore()
Protected Overridable Function IsPasswordCore() As bool
Returns
Platform::Boolean bool bool

true if the element contains sensitive content; otherwise, false.

Remarks

The standard implementation returns false. PasswordBoxAutomationPeer provides an implementation that returns true. If the peer being returned by your control is PasswordBoxAutomationPeer or derived from it, you will inherit that behavior.

See Also

IsPeripheral() IsPeripheral() IsPeripheral()

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

public : Platform::Boolean IsPeripheral()
public bool IsPeripheral()
Public Function IsPeripheral() As bool
Returns
Platform::Boolean bool bool

A Boolean value that indicates whether the automation element represents peripheral UI.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Peripheral UI appears and supports user interaction, but does not take keyboard focus when it appears. Examples of peripheral UI include popups, flyouts, context menus, or floating notifications.

IsPeripheralCore() IsPeripheralCore() IsPeripheralCore()

Provides the peer’s behavior when a Microsoft UI Automation client accesses IsPeripheral or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsPeripheralCore()
protected virtual bool IsPeripheralCore()
Protected Overridable Function IsPeripheralCore() As bool
Returns
Platform::Boolean bool bool

A Boolean value that indicates whether the automation element represents peripheral UI.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

IsRequiredForForm() IsRequiredForForm() IsRequiredForForm()

Gets a value that indicates whether the element that is associated with this peer must be completed on a form.

public : Platform::Boolean IsRequiredForForm()
public bool IsRequiredForForm()
Public Function IsRequiredForForm() As bool
Returns
Platform::Boolean bool bool

true if the element must be completed; otherwise, false.

IsRequiredForFormCore() IsRequiredForFormCore() IsRequiredForFormCore()

Provides the peer's behavior when a Microsoft UI Automation client calls IsRequiredForForm or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Boolean IsRequiredForFormCore()
protected virtual bool IsRequiredForFormCore()
Protected Overridable Function IsRequiredForFormCore() As bool
Returns
Platform::Boolean bool bool

true if the element must be completed; otherwise, false.

Remarks

The standard implementation returns false. Overriding this value at the peer level to return true is probably an uncommon scenario, because you are implying that every instance of your control has a required-for-form behavior no matter what app or UI situation it is used for. It's more typical for apps to specify a required-for-form behavior that is declared in the app's XAML UI definitions, by setting AutomationProperties.IsRequiredForForm.

See Also

ListenerExists(AutomationEvents) ListenerExists(AutomationEvents) ListenerExists(AutomationEvents)

Gets a value that indicates whether Microsoft UI Automation reports that a client is listening for the specified event.

public : static Platform::Boolean ListenerExists(AutomationEvents eventId)
public static bool ListenerExists(AutomationEvents eventId)
Public Static Function ListenerExists(eventId As AutomationEvents) As bool
Parameters
eventId
AutomationEvents AutomationEvents AutomationEvents

One of the enumeration values.

Returns
Platform::Boolean bool bool

true if Microsoft UI Automation reports a client is listening for the specified event; otherwise, false.

Navigate(AutomationNavigationDirection) Navigate(AutomationNavigationDirection) Navigate(AutomationNavigationDirection)

Gets the element in the specified direction within the UI automation tree.

public : Platform::Object Navigate(AutomationNavigationDirection direction)
public object Navigate(AutomationNavigationDirection direction)
Public Function Navigate(direction As AutomationNavigationDirection) As object
Parameters
Returns
Platform::Object object object

The element in the specified direction within the UI automation tree.

NavigateCore(AutomationNavigationDirection) NavigateCore(AutomationNavigationDirection) NavigateCore(AutomationNavigationDirection)

Provides the peer’s behavior when a Microsoft UI Automation client calls Navigate or an equivalent Microsoft UI Automation client API.

protected : virtual Platform::Object NavigateCore(AutomationNavigationDirection direction)
protected virtual object NavigateCore(AutomationNavigationDirection direction)
Protected Overridable Function NavigateCore(direction As AutomationNavigationDirection) As object
Parameters
Returns
Platform::Object object object

The element in the specified direction within the UI automation tree.

PeerFromProvider(IRawElementProviderSimple) PeerFromProvider(IRawElementProviderSimple) PeerFromProvider(IRawElementProviderSimple)

Gets an AutomationPeer for the specified IRawElementProviderSimple proxy.

protected : AutomationPeer PeerFromProvider(IRawElementProviderSimple provider)
protected AutomationPeer PeerFromProvider(IRawElementProviderSimple provider)
Protected Function PeerFromProvider(provider As IRawElementProviderSimple) As AutomationPeer
Parameters
Returns

ProviderFromPeer(AutomationPeer) ProviderFromPeer(AutomationPeer) ProviderFromPeer(AutomationPeer)

Gets the IRawElementProviderSimple proxy for the specified AutomationPeer.

protected : IRawElementProviderSimple ProviderFromPeer(AutomationPeer peer)
protected IRawElementProviderSimple ProviderFromPeer(AutomationPeer peer)
Protected Function ProviderFromPeer(peer As AutomationPeer) As IRawElementProviderSimple
Parameters
peer
AutomationPeer AutomationPeer AutomationPeer

The automation peer.

Returns

RaiseAutomationEvent(AutomationEvents) RaiseAutomationEvent(AutomationEvents) RaiseAutomationEvent(AutomationEvents)

Raises an automation event.

public : void RaiseAutomationEvent(AutomationEvents eventId)
public void RaiseAutomationEvent(AutomationEvents eventId)
Public Function RaiseAutomationEvent(eventId As AutomationEvents) As void
Parameters
eventId
AutomationEvents AutomationEvents AutomationEvents

The event identifier for the event to raise, as a value of the enumeration. See AutomationEvents.

RaiseNotificationEvent(AutomationNotificationKind, AutomationNotificationProcessing, String, String) RaiseNotificationEvent(AutomationNotificationKind, AutomationNotificationProcessing, String, String) RaiseNotificationEvent(AutomationNotificationKind, AutomationNotificationProcessing, String, String)

Initiates a notification event.

public : void RaiseNotificationEvent(AutomationNotificationKind notificationKind, AutomationNotificationProcessing notificationProcessing, Platform::String displayString, Platform::String activityId)
public void RaiseNotificationEvent(AutomationNotificationKind notificationKind, AutomationNotificationProcessing notificationProcessing, String displayString, String activityId)
Public Function RaiseNotificationEvent(notificationKind As AutomationNotificationKind, notificationProcessing As AutomationNotificationProcessing, displayString As String, activityId As String) As void
Parameters
notificationKind
AutomationNotificationKind AutomationNotificationKind AutomationNotificationKind

Specifies the type of the notification.

notificationProcessing
AutomationNotificationProcessing AutomationNotificationProcessing AutomationNotificationProcessing

Specifies the order in which to process the notification.

displayString
Platform::String String String

A display string describing the event.

activityId
Platform::String String String

A unique non-localized string to identify an action or group of actions. Use this to pass additional information to the event handler.

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

RaisePropertyChangedEvent(AutomationProperty, Object, Object) RaisePropertyChangedEvent(AutomationProperty, Object, Object) RaisePropertyChangedEvent(AutomationProperty, Object, Object)

Raises an event to notify the automation client of a changed property value.

public : void RaisePropertyChangedEvent(AutomationProperty automationProperty, Platform::Object oldValue, Platform::Object newValue)
public void RaisePropertyChangedEvent(AutomationProperty automationProperty, Object oldValue, Object newValue)
Public Function RaisePropertyChangedEvent(automationProperty As AutomationProperty, oldValue As Object, newValue As Object) As void
Parameters
automationProperty
AutomationProperty AutomationProperty AutomationProperty

The property that changed.

oldValue
Platform::Object Object Object

The previous value of the property.

newValue
Platform::Object Object Object

The new value of the property.

RaiseStructureChangedEvent(AutomationStructureChangeType, AutomationPeer) RaiseStructureChangedEvent(AutomationStructureChangeType, AutomationPeer) RaiseStructureChangedEvent(AutomationStructureChangeType, AutomationPeer)

Raises an event to notify the Microsoft UI Automation core that the tree structure has changed.

public : void RaiseStructureChangedEvent(AutomationStructureChangeType structureChangeType, AutomationPeer child)
public void RaiseStructureChangedEvent(AutomationStructureChangeType structureChangeType, AutomationPeer child)
Public Function RaiseStructureChangedEvent(structureChangeType As AutomationStructureChangeType, child As AutomationPeer) As void
Parameters
structureChangeType
AutomationStructureChangeType AutomationStructureChangeType AutomationStructureChangeType

The type of change that has occurred.

child
AutomationPeer AutomationPeer AutomationPeer

The element to which the change has been made.

RaiseTextEditTextChangedEvent(AutomationTextEditChangeType, IVectorView) RaiseTextEditTextChangedEvent(AutomationTextEditChangeType, IVectorView) RaiseTextEditTextChangedEvent(AutomationTextEditChangeType, IVectorView)

Raises an event to notify the Microsoft UI Automation core that a text control has programmatically changed text.

public : void RaiseTextEditTextChangedEvent(AutomationTextEditChangeType automationTextEditChangeType, IVectorView<Platform::String> changedData)
public void RaiseTextEditTextChangedEvent(AutomationTextEditChangeType automationTextEditChangeType, IReadOnlyList<String> changedData)
Public Function RaiseTextEditTextChangedEvent(automationTextEditChangeType As AutomationTextEditChangeType, changedData As IReadOnlyList<String>) As void
Parameters
automationTextEditChangeType
AutomationTextEditChangeType AutomationTextEditChangeType AutomationTextEditChangeType

The type of change that was made to the text.

changedData
IVectorView<Platform::String> IReadOnlyList<String> IReadOnlyList<String>

The new text.

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Inherited from DependencyObject

RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Inherited from DependencyObject

SetFocus() SetFocus() SetFocus()

Sets the keyboard focus on the element that is associated with this automation peer.

public : void SetFocus()
public void SetFocus()
Public Function SetFocus() As void

SetFocusCore() SetFocusCore() SetFocusCore()

Provides the peer's behavior when a Microsoft UI Automation client calls SetFocus or an equivalent Microsoft UI Automation client API.

protected : virtual void SetFocusCore()
protected virtual void SetFocusCore()
Protected Overridable Function SetFocusCore() As void

Remarks

The standard implementation uses IsKeyboardFocusable to determine whether the peer reports that the owner can be focused. FrameworkElementAutomationPeer adds behavior that performs the actual focus operation if it is possible.

See Also

SetParent(AutomationPeer) SetParent(AutomationPeer) SetParent(AutomationPeer)

Sets the AutomationPeer that is the parent of this AutomationPeer.

public : void SetParent(AutomationPeer peer)
public void SetParent(AutomationPeer peer)
Public Function SetParent(peer As AutomationPeer) As void
Parameters
peer
AutomationPeer AutomationPeer AutomationPeer

The parent automation peer.

Remarks

You can't re-parent an AutomationPeer for a UWP app. This functionality is only available for a Windows Phone 8.x app.

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Inherited from DependencyObject

ShowContextMenu() ShowContextMenu() ShowContextMenu()

Shows the available context menu for the owner element.

public : void ShowContextMenu()
public void ShowContextMenu()
Public Function ShowContextMenu() As void

Remarks

Calling ShowContextMenu throws an error if a context menu cannot be shown. If no context menu is available directly on the element on which it was invoked, the Microsoft UI Automation logic implemented by a provider should attempt to show a context menu for the Microsoft UI Automation tree parent of the element.

Scenarios for invoking a context menu from an element include auto-correction and spelling alternatives for text input. The UI elements that display these are not part of the default tab sequence and are not part of an initial Microsoft UI Automation tree until the context that requires them is detected.

ShowContextMenuCore() ShowContextMenuCore() ShowContextMenuCore()

Provides the peer's behavior when a Microsoft UI Automation client calls ShowContextMenu or an equivalent Microsoft UI Automation client API.

protected : virtual void ShowContextMenuCore()
protected virtual void ShowContextMenuCore()
Protected Overridable Function ShowContextMenuCore() As void

UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Inherited from DependencyObject

See Also