FrameworkElementAutomationPeer.CreatePeerForElement(UIElement) Method

Reference

Definition

Namespace:: Windows.UI.Xaml.Automation.Peers

Important

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

Edit

Creates a FrameworkElementAutomationPeer for the specified UIElement.

public:
 static AutomationPeer ^ CreatePeerForElement(UIElement ^ element);

 static AutomationPeer CreatePeerForElement(UIElement const& element);

public static AutomationPeer CreatePeerForElement(UIElement element);

function createPeerForElement(element)

Public Shared Function CreatePeerForElement (element As UIElement) As AutomationPeer

Parameters

element: UIElement

The UIElement that is associated with this FrameworkElementAutomationPeer.

Returns

AutomationPeer

A FrameworkElementAutomationPeer.

Examples

CreatePeerForElement 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 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);
}

Remarks

CreatePeerForElement 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 and calls to FromElement 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 returns null. As a best practice you should always check for null after calling CreatePeerForElement, 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 has basically the same behavior as FromElement.

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

Applies to