FrameworkElement.FindName Method

Syntax

'Declaration
Public Function FindName ( _
    name As String _
) As Object

public Object FindName(
    string name
)

Remarks

Important Note:
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 information about XAML namescope concepts, see XAML Namescopes.

The following is a summary of some key XAML namescope concepts:

• A run-time API such as FindName is working against an object tree. These objects are loaded into the content area and the CLR runtime engine of the overall Silverlight plug-in. When part of the object tree is created from templates or run-time loaded XAML, a XAML namescope is typically not contiguous with the entirety of that object tree. The result is that there might be a named object in the object tree that a given FindName call 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 main object tree.

• If you return an unexpected null result for FindName, the following might be some techniques for finding the named object you are interested in:

  • For named objects that come from a template, if you are authoring 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 the object lifetime after the template is applied. However, 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.

  • For the XamlReader.Load case, 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 equivalent x:Name XAML directive) 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). You can specify a Name as part of the XAML input for calls to Load, but note that any such name created will be in a discrete XAML namescope, which extends only to the root equivalent of the XAML input provided. If you call Load and subsequently add the created objects to the main object tree , this consideration will affect how you call FindName, and from what programming scope you should call it.

TextElement defines a similar FindName. This enables a FindName behavior in the Silverlight text object model, which is not based on 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.

Note:
Instead of using FindName, a templated control generally uses GetTemplateChild to find the named parts of its template, as part of its OnApplyTemplate override. This is necessary in order to join class logic and element references from the XAML-defined templates. For more information on this concept, see Creating a New Control by Creating a ControlTemplate.

Examples

The following example uses FindName to find a named element from a XAML page that was just loaded as a component. In this case, you cannot just refer to the named element as its field reference, because in absence of a call to the typically generated InitializeComponent, that field does not exist.

Private LayoutRoot As System.Windows.Controls.Grid

Public Sub New()
    System.Windows.Application.LoadComponent(Me, New System.Uri( _
        "/SilverlightApplication1;component/Page.xaml", _
        System.UriKind.Relative))
    Me.LayoutRoot = CType(Me.FindName("LayoutRoot"),  _
        System.Windows.Controls.Grid)
End Sub

private System.Windows.Controls.Grid LayoutRoot;

public Page()
{
    System.Windows.Application.LoadComponent(this, new System.Uri(
        "/SilverlightApplication1;component/Page.xaml", 
        System.UriKind.Relative));
    this.LayoutRoot = ((System.Windows.Controls.Grid)
        (this.FindName("LayoutRoot")));
}

(You can see similar code if you examine the actual definition of InitializeComponent from generated code that is produced by the XAML compilation build action for Silverlight pages. Note the succession of FindName calls that assign the field reference values for each named element, and therefore, make those field references available for use by any runtime calls from the code-behind.)

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

See Also

Reference

Other Resources