| -api-id | -api-type |
|---|---|
M:Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer.CreatePeerForElement(Microsoft.UI.Xaml.UIElement) |
winrt method |
Creates a FrameworkElementAutomationPeer for the specified UIElement.
The UIElement that is associated with this FrameworkElementAutomationPeer.
A FrameworkElementAutomationPeer.
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.
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);
}