FrameworkElementAutomationPeer FrameworkElementAutomationPeer FrameworkElementAutomationPeer Class

Exposes FrameworkElement derived types (including all controls) to Microsoft UI Automation.

Syntax

Declaration

public class FrameworkElementAutomationPeerpublic class FrameworkElementAutomationPeerPublic Class FrameworkElementAutomationPeer

Inheritance Hierarchy

Inherited Members

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited properties

,

Windows.UI.Xaml.Automation.Peers.AutomationPeer.RaiseTextEditTextChangedEvent(Windows.UI.Xaml.Automation.AutomationTextEditChangeType,Windows.Foundation.Collections.IVectorView<System.String>)
Windows.UI.Xaml.Automation.Peers.AutomationPeer.RaiseTextEditTextChangedEvent(Windows.UI.Xaml.Automation.AutomationTextEditChangeType,Windows.Foundation.Collections.IVectorView<System.String>)
Windows.UI.Xaml.Automation.Peers.AutomationPeer.RaiseTextEditTextChangedEvent(Windows.UI.Xaml.Automation.AutomationTextEditChangeType,Windows.Foundation.Collections.IVectorView<System.String>)

Remarks

There is no "ControlAutomationPeer" class. FrameworkElementAutomationPeer serves as implementation for all basic Control class scenarios that involve Microsoft UI Automation. This includes behavior that does not necessarily appear as a public API exposure, such as the practical implementations of many of the Core methods from AutomationPeer.

FrameworkElementAutomationPeer includes extensive base implementation of peer behavior that other peers can use to report information that comes from owner classes at the UIElement and FrameworkElement level. For more info, see the "Base implementation in FrameworkElementAutomationPeer" section of Custom automation peers.

In addition to the Core overrides, FrameworkElementAutomationPeer has two static utility methods that are useful for getting a peer handle from within control code, or for generating items peers from an item container peer for Microsoft UI Automation support. These are:

If you have a need to define a custom automation peer and can't identify a more derived peer class that pairs up with the control or base class you are deriving the owner class from, you should base your peer on FrameworkElementAutomationPeer. Even if the owner class isn't necessarily a FrameworkElement, you can't practically derive peers from AutomationPeer directly because FrameworkElementAutomationPeer has many overrides that provide the expected behavior for layout, automation and UI interactions. You do need to derive your owner class from UIElement at least, otherwise there is no way to create the peer on automation tree load with OnCreateAutomationPeer().

FrameworkElementAutomationPeer derived classes

FrameworkElementAutomationPeer is the parent class for several immediately derived classes that implement peer support for Windows Runtime controls and elements. Some of these peer classes are peers that match control base classes rather than practical controls. For example ButtonBaseAutomationPeer exists so that it can define shared peer behavior for several classes that support the practical Button classes that derive from ButtonBase. Here is the list of classes that directly derive from FrameworkElementAutomationPeer:

Examples

This example shows the basic subclass requirements for deriving a peer from FrameworkElementAutomationPeer and supporting at least one control pattern. This code is an excerpt from the XAML accessibility sample.

        public class MediaContainerAP : FrameworkElementAutomationPeer, IRangeValueProvider, IToggleProvider
        {
            MediaElement _mediaElement;
            FrameworkElement _labeledBy;
// nondefault ctors omitted
            protected override object GetPatternCore(PatternInterface patternInterface)
            {
                if (patternInterface == PatternInterface.RangeValue)
                {
                    return this;
                }
                else if (patternInterface == PatternInterface.Toggle)
                {
                    return this;
                }
                return null;
            }


            protected override AutomationControlType GetAutomationControlTypeCore()
            {
                return AutomationControlType.Group;
            }

            protected override string GetLocalizedControlTypeCore()
            {
                return "Video";
            }

            protected override string GetClassNameCore()
            {
                return "MediaElementContainer";
            }
// pattern implementation omitted ...
        }
    Public Class MediaContainerAP
        Inherits FrameworkElementAutomationPeer
        Implements IRangeValueProvider
        Implements IToggleProvider
' nondefault ctors omitted ...

        Protected Overrides Function GetPatternCore(patternInterface__1 As PatternInterface) As Object
            If patternInterface__1 = PatternInterface.RangeValue Then
                Return Me
            ElseIf patternInterface__1 = PatternInterface.Toggle Then
                Return Me
            End If
            Return Nothing
        End Function


        Protected Overrides Function GetAutomationControlTypeCore() As AutomationControlType
            Return AutomationControlType.Group
        End Function

        Protected Overrides Function GetLocalizedControlTypeCore() as String
            Return "Video"
        End Function

        Protected Overrides Function GetClassNameCore() As String
            Return "MediaElementContainer"
        End Function
' pattern implementation omitted ...
End Class
// header
        public ref class MediaContainerAP sealed :  Windows::UI::Xaml::Automation::Peers::FrameworkElementAutomationPeer
                                                    ,Windows::UI::Xaml::Automation::Provider::IRangeValueProvider
                                                    ,Windows::UI::Xaml::Automation::Provider::IToggleProvider
        {
// nondefault ctors omitted
        protected: 
            virtual Object^ GetPatternCore(PatternInterface patternInterface) override
            {
                if (patternInterface == PatternInterface::RangeValue)
                {
                    return this;
                }
                else if (patternInterface == PatternInterface::Toggle)
                {
                    return this;
                }
                return nullptr;
            }

        protected:
            virtual  AutomationControlType GetAutomationControlTypeCore() override
            {
                return  AutomationControlType::Group;
            }

        protected:
            virtual Platform::String^ GetLocalizedControlTypeCore() override
            {
                return "Video";
            }

        protected:
            virtual Platform::String^ GetClassNameCore() override
            {
                return "MediaElementContainer";
            }
// pattern implementation omitted

Constructors summary

Initializes a new instance of the FrameworkElementAutomationPeer class.

Properties summary

Gets the UIElement owner that is associated with this FrameworkElementAutomationPeer.

Methods summary

Creates a FrameworkElementAutomationPeer for the specified UIElement.

Returns the FrameworkElementAutomationPeer for the specified UIElement.

Constructors

  • FrameworkElementAutomationPeer(FrameworkElement)
    FrameworkElementAutomationPeer(FrameworkElement)
    FrameworkElementAutomationPeer(FrameworkElement)
    FrameworkElementAutomationPeer(FrameworkElement)

    Initializes a new instance of the FrameworkElementAutomationPeer class.

    public FrameworkElementAutomationPeer(FrameworkElement owner)public New(FrameworkElement owner)Public Sub New(owner As FrameworkElement)public FrameworkElementAutomationPeer(FrameworkElement owner)

    Parameters

Properties

  • Owner
    Owner
    Owner
    Owner

    Gets the UIElement owner that is associated with this FrameworkElementAutomationPeer.

    public UIElement Owner { get; }public UIElement Owner { get; }Public ReadOnly Property Owner As UIElementpublic UIElement Owner { get; }

    Property Value

Methods

  • CreatePeerForElement(UIElement)
    CreatePeerForElement(UIElement)
    CreatePeerForElement(UIElement)
    CreatePeerForElement(UIElement)

    Creates a FrameworkElementAutomationPeer for the specified UIElement.

    public static AutomationPeer CreatePeerForElement(UIElement element)public static AutomationPeer CreatePeerForElement(UIElement element)Public Static Function CreatePeerForElement(element As UIElement) As AutomationPeerpublic static AutomationPeer CreatePeerForElement(UIElement element)

    Parameters

    Returns

    Remarks

    CreatePeerForElement(UIElement) is a helper class that is used by custom control code to return the acting peer instance. Using the returned peer, you can fire automation events from within the same routines that also fire your general control logic events or change control properties. Or you can write your own helper methods that do this and are invoked from your control logic.

    The created FrameworkElementAutomationPeer remains in memory until the associated UIElement is destroyed. The same instance of the FrameworkElementAutomationPeer is returned from subsequent calls to CreatePeerForElement(UIElement) and calls to FromElement(UIElement) that reference the same element instance.

    The type of the peer returned is determined by the OnCreateAutomationPeer() implementation of the relevant UIElement, which is typically a Control. If the class code for the element type doesn't implement OnCreateAutomationPeer(), no peer is created, and CreatePeerForElement(UIElement) returns null. As a best practice you should always check for null after calling CreatePeerForElement(UIElement), because there are a number of Windows Runtime elements that won't have an OnCreateAutomationPeer() implementation. For example, a ContentControl doesn't have a peer by default unless it's customized or is a more-derived Windows Runtime control.

    CreatePeerForElement(UIElement) has basically the same behavior as FromElement(UIElement).

    CreatePeerForElement(UIElement) can return the peer even if the CreateAutomationPeer system logic hasn't run yet on the element target for some reason. It will invoke the same CreateAutomationPeer logic internally in order to get the peer.

    Examples

    CreatePeerForElement(UIElement) is useful if you are writing a peer that forwards the peer information from one of its component parts, because it's the component part that might implement a pattern as requested in the peer's GetPatternCore(PatternInterface) implementation. For example, if one of a control's main component parts is a ScrollViewer the control itself may have some other function and doesn't scroll directly. But the peer might still want to report support for a Scroll pattern, and provide a peer so that a client can interact with the automation pattern of the scrolling part.

    protected override object GetPatternCore(PatternInterface patternInterface)
    {
        if (patternInterface == PatternInterface.Scroll)
        {
            ItemsControl owner = (ItemsControl) base.Owner;
            UIElement itemsHost = owner.ItemsHost;
            ScrollViewer element = null;
            while (itemsHost != owner)
            {
                itemsHost = VisualTreeHelper.GetParent(itemsHost) as UIElement;
                element = itemsHost as ScrollViewer;
                if (element != null)
                {
                    break;
                }
            }
            if (element != null)
            {
                AutomationPeer peer = FrameworkElementAutomationPeer.CreatePeerForElement(element);
                if ((peer != null) && (peer is IScrollProvider))
                {
                    return (IScrollProvider) peer;
                }
            }
        }
        return base.GetPatternCore(patternInterface);
    }
    
  • FromElement(UIElement)
    FromElement(UIElement)
    FromElement(UIElement)
    FromElement(UIElement)

    Returns the FrameworkElementAutomationPeer for the specified UIElement.

    public static AutomationPeer FromElement(UIElement element)public static AutomationPeer FromElement(UIElement element)Public Static Function FromElement(element As UIElement) As AutomationPeerpublic static AutomationPeer FromElement(UIElement element)

    Parameters

    Returns

    Remarks

    FromElement(UIElement) is a helper class that is used by custom control code to return the acting peer instance. Using the returned peer, you can fire automation events from within the same routines that also fire your general control logic events or change control properties. Or you can write your own helper methods that do this and are invoked from your control logic.

    CreatePeerForElement(UIElement) has basically the same behavior as FromElement(UIElement).

    If FromElement(UIElement) returns null, it's probably because the element you passed does not have an implementation for OnCreateAutomationPeer().

    FromElement(UIElement) can return the peer even if the CreateAutomationPeer system logic hasn't run yet on the element target for some reason. It will invoke the same CreateAutomationPeer logic internally in order to get the peer.

    Examples

    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 MyDownAutomationPeer = _
        TryCast(FrameworkElementAutomationPeer.FromElement(myCtrl), MyAutomationPeer)
        If peer IsNot Nothing Then
            peer.RaisePropertyChangedEvent(RangeValuePatternIdentifiers.ValueProperty, CDbl(oldValue), CDbl(newValue))
        End If
    End If
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Automation.Peers.dll