IXRFrameworkElement::FindName (Compact 2013)
3/28/2014
This method retrieves the element that has the specified name.
Syntax
virtual HRESULT STDMETHODCALLTYPE FindName(
__in const WCHAR *pName,
__out IXRDependencyObject** ppFoundObject
) = 0;
Parameters
- pName
[in] Pointer to a string that specifies the name of the element in the element tree that you want to find.
- ppFoundObject
[out] Address of an IXRDependencyObject pointer that on return references the object that represents the element that has the specified name.
Return Value
Returns an HRESULT that indicates success or failure.
Returns XR_E_ELEMENT_NOT_FOUND if this method was unable to locate the type requested.
If you call this method with pName set to the x:Name of a <UserControl> root element parsed from XAML before the PFN_CREATE_CONTROL function finishes creating a control from the element, it returns XR_E_ELEMENT_NOT_CREATED.
Remarks
If this IXRFrameworkElement object has child elements in the element tree, the FindName method searches these child elements recursively for the requested named element. Generally, a FindName call searches the current XAML namescope, in both the "up" and "down" directions with regard to the element tree.
To call this method on an IXRFrameworkElement object that represents the root of the visual tree, use the object returned by IXRVisualHost::GetRootElement.
After the source XAML has been parsed into a visual tree, all the XAML elements are stored as objects in the tree structure and can be located by supplying the element's x:Name into pName. If you created an object in C++ and added it to the visual tree after loading the XAML, you can also locate it by calling this method. However, the object you created must be derived from IXRDependencyObject, and you must set a name for it by calling IXRDependencyObject::SetName.
The Name property for an element, or the equivalent x:Name attribute in XAML, is assigned to an element in XAML markup. You can also access and modify the Name property in C++ code-behind by using IXRDependencyObject::GetName and IXRDependencyObject::SetName.
If a UI designer has created the XAML file that your application loads, you must make sure that the element names provided in the XAML file match up with the element names specified in calls to FindName.
If you call this method on the root IXRFrameworkElement object of the visual tree, the method traverses the entire visual tree to search for the object that has the specified name. If you call this method on an IXRFrameworkElement derived object in the visual tree, the method traverses the child elements of that object. Therefore, if a parent object stores a collection and you want to locate an item in that collection by supplying a name instead of supplying an index, you can call this method on the parent object.
To use a specific interface pointer type, you can use the helper template version of this method that XAML for Windows Embedded provides. When you supply a derived type, this version automatically supplies a type-safe method that implicitly converts the returned type from a generic interface so you do not have to explicitly call QueryInterface to convert the generic interface into the required object type.
Example
The following code example shows how to use FindName to locate an element in your source XAML file after the element was parsed into an object in the visual tree, and then obtain a pointer to that object.
Note
To make the following code example easier to read, security checking and error handling are not included. This code sample should not be used in a release configuration unless it has been modified to include them.
#include "stdafx.h"
#include <XamlRuntime.h>
#include <XRPtr.h>
XRXamlSource Source;
IXRApplicationPtr pApplication;
IXRVisualHostPtr pVisualHost;
Source.SetFile(L"ListBoxChanger.xaml");
// Create an application instance and load the XAML source into a
// visual tree
XamlRuntimeInitialize();
GetXRApplicationInstance(&pApplication);
pApplication->CreateHostFromXaml(&Source, NULL, &pVisualHost);
// Obtain the root element
IXRFrameworkElementPtr pRootElement;
IXRStackPanelPtr pPanel;
pVisualHost->GetRootElement(&pRootElement);
// Find the stack panel in the visual tree
pRootElement->FindName(L"MyStackPanel", &pPanel);
IXRTextBlockPtr pTextBlock;
// Find a UI element in the child collection of the stack panel, and
// modify it at run time
pPanel->FindName(L"StackPanelChildButton", &pTextBlock);
pTextBlock->SetText(L"This is Custom Text Set at Run Time");
pTextBlock->InvalidateMeasure();
For more information on the programming elements used in this code example, see IXRApplication, XRXamlSource, IXRVisualHost, IXRPanel, and IXRTextBlock.
.NET Framework Equivalent
System.Windows.FrameworkElement.FindName
Requirements
Header |
XamlRuntime.h |
sysgen |
SYSGEN_XAML_RUNTIME |