FrameworkElement.FindName(String) Method

Definition

Namespace:

Microsoft.UI.Xaml

Retrieves an object that has the specified identifier name.

public:
 virtual Platform::Object ^ FindName(Platform::String ^ name) = FindName;

IInspectable FindName(winrt::hstring const& name);

public object FindName(string name);

function findName(name)

Public Function FindName (name As String) As Object

Parameters

name

String

Platform::String

winrt::hstring

The name of the requested object.

Returns

Object

Platform::Object

IInspectable

The requested object. This can be null if no matching object was found in the current XAML namescope.

Remarks

Important

In order to use the FindName method effectively, you should understand the concept of a XAML namescope, and how a XAML namescope is created at XAML load time and then referenced and possibly modified at run time. For more info see XAML namescopes.

The most common usage of FindName in your Windows Runtime code will be from within the generated InitializeComponent call for a XAML page. In this situation, FindName is invoked only after the XAML page is loaded. InitializeComponent provides the infrastructure such that any object that was instantiated by XAML loading can conveniently be accessed by your code-behind code. You can then reference the objects as a variable that shares the same name as the markup-declared x:Name attribute.

A run-time API such as FindName is working against a run-time object tree of the app as it exists in memory. When part of this object tree is created from templates or run-time loaded XAML, a XAML namescope is typically not contiguous within that object tree. The result is that there might be a named object in the object tree that a given FindName scope cannot find. The discontinuities between XAML namescopes that you might encounter in typical application scenarios are when objects are created by applying a template, or when objects are created by a call to XamlReader.Load and subsequently added to the object tree.

If you return an unexpected null result for FindName, try these techniques:

• For named objects that come from a template, if you are defining or deriving from a control, you can call GetTemplateChild from the scope of the object where the template is applied. You must be in a derived-class definition scope in order to use GetTemplateChild, because it is a protected method of Control.
• If you are not in a derived-class definition scope, you may be able to enter the visual tree of a template, by using VisualTreeHelper at a point in object lifetime after the template is applied (handle the Loaded event). VisualTreeHelper uses a parent-child metaphor for walking the tree, rather than using the XAML namescope concept. Walking the tree generally requires a specific knowledge of the control's composition as it comes from a given template. You can use VisualTreeHelper.GetChild on the control to get the control's applied template root, and call FindName specifically on the template root to access elements that are named within the template XAML.
• For the XamlReader.Load case, you should preserve a reference to the return value of the XamlReader.Load call, which is an object that will become the owner or basis of the created XAML namescope that is relevant. Then call FindName from that scope instead.

The object returned by FindName is not necessarily a FrameworkElement. For example, you might apply a name to an animation storyboard, and the various animation storyboard types do not derive from FrameworkElement.

The Name property for an object (or the similar x:Name attribute) is assigned by specifying an attribute on an object element in XAML markup. You can set a Name value after the initial source XAML is loaded, but this technique has some limitations (see Remarks in Name).

TextElement defines a similar FindName. This enables a FindName behavior in the object model, which is not limited to FrameworkElement. Calls by either implementation of FindName can traverse into a mixed FrameworkElement / text element object tree, and use a common XAML namescope so that a FrameworkElement.FindName call can find a named text element, and vice versa.

Name values that are added or changed at run time in the object tree will update into the acting XAML namescope at that level in the object tree. In other words, if you create a new FrameworkElement, give it a Name, then add it to the object tree, calling FindName from within that XAML namescope can find and return the code-created object.

See also

• Name
• XAML namescopes
• x:Name attribute