FindName, CreateFromXAML, and XAML name fan in the Silverlight-javascript API

Object Tree and FindName

In the JavaScript API, the initial object tree is always constructed by parsing XAML. In addition to some type conversion usages that can parse strings, loading XAML is the only way to "construct" objects in the JavaScript API. After you construct such a tree, you will typically want to interact with that object tree. To do this, you need a script object to reference an object in the tree.

The best way to establish such a reference is to assign the Name or x:name property to any object element in the XAML that is scheduled to reference the object during run time. In the JavaScript API, the name is conceptually just a string, not an object. However, you can then use the name string to retrieve the actual object by calling FindName in any run-time code. FindName exists in this way in the API: You can call FindName on almost all objects in the JavaScript API, including objects that represent Silverlight plug-ins. You will typically find that the first row or several previous FindName calls to the user function written for the JavaScript API for Silverlight Get the object reference, and then the rest of the function operates on those objects.

Even if you do not have a named object, you can still enter the object tree at run time through the Root property on the Silverlight plug-in. This returns the object that is the root of the loaded XAML.

In addition, any event handlers attached to the Silverlight object have permission to access the sender value from the event. This sender and related event handlers are often attached in such a way that the sender is the object that you want to interact with. If this is not the case, sender still provides a convenient object from which to invoke FindName.

Object Tree and CreateFromXAML

Silverlight content on a Web page is arranged by the object hierarchy in the tree structure. The topmost object in the structure is the root object and corresponds to the root of the XAML file loaded as the Silverlight plug-in's Source. The root object is usually a Canvas object, because Canvas can contain other objects, such as TextBlock or MediaElement. (Silverlight 1.0 supports only Canvas as a root, and if the JavaScript API is used with Silverlight 2 clients, other UIElement objects can be used as the root.) ）

To dynamically add XAML content to the tree after initial loading of the source XAML, use the CreateFromXAML method to create the XAML fragment first. At this point, the XAML fragment created is disconnected from the Silverlight object tree. This means that the fragment has not been rendered. However, you can modify the properties of an object in the XAML fragment even before adding it to the object tree. Object methods cannot be called before connecting to the tree.

After you create a set of objects that are disconnected from a XAML fragment, you will typically want to add the object set to the active Silverlight object tree. You can add the fragment as a child object to a parent object, or you can set the fragment as a property value for an object. When the fragment becomes part of the Silverlight object tree, the objects in that XAML fragment are rendered. Depending on the XAML scope provided as a CreateFromXAML input, you can create a Silverlight object (such as TextBlock) or a complex Silverlight object tree.

There are several requirements for dynamically adding XAML content to the Silverlight object tree:

There must be an existing XAML content associated with the Silverlight plug-in. You cannot replace the entire content tree with CreateFromXAML; You must keep at least the original root element. If you want to replace the entire tree, you can set source, but note that source requires that the actual file exists at the URI and cannot be initialized with only strings. However, you can work around this problem by using inline XAML as Source, using the HTML DOM to document.write the contents of the SCRIPT block that contains the expected source XAML.

The CreateFromXAML method can only be invoked by the Silverlight plug-in. However, it is easy to get an object reference to the plug-in in the JavaScript API: simply invoke GetHost on any Silverlight object.

Only XAML content created using the CreateFromXAML method can be assigned to an object. If you want to add objects created from the same XAML to different areas of your application, you must call CreateFromXAML multiple times and use a different variable for the return value. (If you do this, be careful with name collisions; see the use of CreateFromXAML to create a name range later in this topic.) ）

The Silverlight object that will contain the new XAML content must be able to encapsulate the object, whether as a child element or as a property value.

The string specified for the CreateFromXAML xamlcontent must specify well-formed XML (specifically, it must have a single root element). If the supplied XML string is malformed, CreateFromXAML will fail and cause an error.

The root element implicitly uses the Silverlight XML namespace. You can explicitly set the Silverlight namespace, but do not set the default XML namespace to any other value than the Silverlight namespace.

Create a name range using CreateFromXAML

The XAML used for CreateFromXAML can have values that are defined for either Name or x:name. During the CreateFromXAML call, a preliminary namescope is created based on the root of the provided XAML. This preliminary namescope evaluates whether all defined names in the provided XAML are unique. If the name in the provided XAML is not unique internally at this time, CreateFromXAML will raise an error. However, if the name in the provided XAML conflicts with a name already in the scope of the main object tree name, no error occurs immediately. This is because when the CreateFromXAML method is invoked, the object tree that is returned is disconnected. The object tree that you create must be explicitly connected by adding it to a collection of content attributes (such as Canvas.Children) or by setting another property that takes an object value (for example, specifying a new ImageBrush for the Fill property value). You can see the name conflict that caused the error only after you try to connect the disconnected object tree to the application's main object tree. The method or property used for the attempted connection will be the source of the error, and the attempted connection will fail (the disconnected tree will remain disconnected).

CreateFromXAML has an optional parameter createnamescope, which usually defaults to false. If the value is explicitly set to true in the CreateFromXAML call used to create the disconnected object tree, a preliminary namescope is still created to calculate whether all defined names in the provided XAML are unique. If the name in the provided XAML is not unique internally at this time, CreateFromXAML will raise an error. The difference in behavior is that the disconnected object tree will then be marked, and when it is connected to the main application Object tree, it will not attempt to merge its name scope with the main application name range. In fact, after the tree is connected, the application will have a unified object tree instead of a separate name range. The name defined on any object in the CreateFromXAML root or previously disconnected tree is not associated with the primary object Tree name range, and it has its own independent name range.

Having a separate name range can cause the following problems: Calls to the FindName method will no longer perform operations on the uniform name range. Instead, a specific object that invokes FindName will represent a scope, which is the range of names in which the calling object resides. Therefore, if you try to call FindName to get the named object in the primary object Tree name range, you will not find an object in the stand-alone name range created by CreateFromXAML. Conversely, calling FindName from a stand-alone name range will not find the named object in the main application name range. The FindName method defined on the Silverlight plug-in object does not completely resolve the problem; its name range is always the primary object Tree name range.

This standalone name scope issue affects only the name range and FindName calls. In some cases, you can still perform the detach step up by calling the GetParent method, or by calling the associated collection property or property (such as the collection returned by Canvas.Children) down.

To get objects that are defined in different name ranges, you can use the following kinds of techniques:

Executes the entire tree in the detached step using the GetParent and/or collection properties.

If you call from a stand-alone name range and want to get the main object Tree name range, it is always easiest to get a reference to the Silverlight plug-in and then call FindName on it. To perform this action in a single line, the connected script is called as follows:

Returnedobject = object. GetHost (). Content. FindName ("nameToFind");

Where the object is a calling object in a stand-alone name range. The. Content in this syntax is the step leading to the specific Silverlight plug-in child object that defines the FindName method.

If you call from the main object tree name range and want to get an object within a separate name range, the best practice is to plan ahead in your code and keep a reference to the object returned by CreateFromXAML, and then add it to the tree. This object is now a valid object for calling FindName within the scope of a stand-alone name that is created. This object can be persisted as a global variable, otherwise it is passed using the method parameter.