frameworkelementautomationpeer.md

-api-id	-api-type
T:Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer	winrt class

Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer

-description

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

-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:

• CreatePeerForElement
• FromElement

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:

• AppBarAutomationPeer
• ButtonBaseAutomationPeer
• ComboBoxItemAutomationPeer
• DatePickerAutomationPeer
• FlipViewItemAutomationPeer
• FlyoutPresenterAutomationPeer
• GridViewItemAutomationPeer
• GroupItemAutomationPeer
• HubAutomationPeer
• HubSectionAutomationPeer
• ItemsControlAutomationPeer
• ListBoxItemAutomationPeer
• ListViewBaseHeaderItemAutomationPeer
• ListViewItemAutomationPeer
• MediaPlayerElementAutomationPeer
• MenuFlyoutItemAutomationPeer
• PasswordBoxAutomationPeer
• ProgressRingAutomationPeer
• RangeBaseAutomationPeer
• RichEditBoxAutomationPeer
• RichTextBlockAutomationPeer
• RichTextBlockOverflowAutomation
• ScrollViewerAutomationPeer
• SemanticZoomAutomationPeer
• TextBlockAutomationPeer
• TextBoxAutomationPeer
• ThumbAutomationPeer
• TimePickerAutomationPeer
• ToggleMenuFlyoutItemAutomationPeer
• ToggleSwitchAutomationPeer

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

Note

This sample is not maintained and might not compile.

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

MIDL 3.0 files for the C++/WinRT code example that follows.

// MediaElementContainer.idl
namespace MyNamespace
{
    runtimeclass MediaElementContainer : Windows.UI.Xaml.Controls.ContentControl
    {
        MediaElementContainer(Windows.UI.Xaml.Controls.Panel parent);
        ...
    };
}

// MediaContainerAP.idl
import "MediaElementContainer.idl";

namespace MyNamespace
{
    runtimeclass MediaContainerAP : Windows.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer,
        Windows.UI.Xaml.Automation.Provider.IRangeValueProvider,
        Windows.UI.Xaml.Automation.Provider.IToggleProvider
    {
        MediaContainerAP(MediaElementContainer owner, Windows.UI.Xaml.Controls.MediaElement mediaElement);
        ...
    };
}

// MediaContainerAP.h
struct MediaContainerAP : MediaContainerAPT<MediaContainerAP>
{
    MediaContainerAP() = delete;
	// Non-default ctors omitted.

    Windows::Foundation::IInspectable GetPatternCore(Windows::UI::Xaml::Automation::Peers::PatternInterface const& patternInterface)
    {
        if (patternInterface == Windows::UI::Xaml::Automation::Peers::PatternInterface::RangeValue)
        {
            return *this;
        }
        else if (patternInterface == Windows::UI::Xaml::Automation::Peers::PatternInterface::Toggle)
        {
            return *this;
        }
        return nullptr;
    }

    Windows::UI::Xaml::Automation::Peers::AutomationControlType GetAutomationControlTypeCore()
    {
        return Windows::UI::Xaml::Automation::Peers::AutomationControlType::Group;
    }

    winrt::hstring GetLocalizedControlTypeCore()
    {
        return L"Video";
    }

    winrt::hstring GetClassNameCore()
    {
        return L"MediaElementContainer";
    }

	// Pattern implementation omitted.
};

// 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

-see-also

FrameworkElement, Custom automation peers, AutomationPeer, Code samples for resolving common programmatic accessibility issues in Windows desktop apps