IXRApplication::CreateObject(IID,Object) (Compact 2013)

3/28/2014

This method creates a new object outside of the element tree that has the specified interface ID (IID). This element can be later added to an existing element tree by adding it either to a collection or as the property value of a UI object.

Syntax

virtual HRESULT STDMETHODCALLTYPE CreateObject(
    REFIID    riid,
    IXRDependencyObject**  ppObject
) = 0;

Parameters

• riid
  [in] Reference to the IID of the object to create.

  To create an IID, you can prefix the name of an object that inherits from IXRDependencyObject with the substring "IID_"; for example, IID_IXREllipse.

• ppObject
  [out] Pointer to an IXRDependencyObject object that provides programmatic access to the new object that you created.

Return Value

Returns an HRESULT that indicates success or failure.

Returns an error if riid is IID_IXRCustomUserControl. riid must be an IID for an interface to any XAML for Windows Embedded object that is not a custom user control. For example, IID_IXRButton, IID_IXRListBox, or IID_IXRSolidColorBrush.

Returns XR_E_ABSTRACT_BASE_CLASS if you try to create an instance of an abstract base class. You must use the IID of a derived class.

Remarks

You can use this method to create UI resources, such as controls, visual elements, and behaviors, directly in C++ code. This can serve as an alternative to creating UI resources by loading XAML markup into a visual tree for your application.

You can also use this method to create additional UI resources in C++ code that you want to add to a visual tree that was created by parsing and loading XAML markup.

You cannot pass the IID of an abstract base class in the riid parameter.

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. With the helper template version, you can supply any IXRDependencyObject-inherited object pointer type for ppObject, or any XAML for Windows Embedded smart pointer (XRPtr<Interface>), as follows:

IXRBitmapImage* pSourceImage = NULL;

pApplication->CreateObject(IID_IXRBitmapImage, &pSourceImage);

Adding the New Object to the Visual Tree

After you create an object by using this method, you must insert it into the appropriate location in the visual tree, to display that object on the GUI window and fully integrate it with XAML for Windows Embedded run-time functionality.

Some kinds of objects must be inserted into object collections that exist in the visual tree. You can obtain a pointer to any object collection and insert an item by calling the Add or Insert method for the object's collection. For example, the gradient stops for an IXRGradientBrush are stored in an IXRGradientStopCollection object. To add to the collection, use the IXRGradientStopCollection::Add or IXRGradientStopCollection::Insert method. The documentation for each collection object indicates how to obtain a pointer to it. For more information, see Classes for Collection Management.

Other kinds of objects must be set as the value of a property that belongs to an object. The object should already exist in the visual tree. After you obtain a pointer to the particular object by calling IXRFrameworkElement::FindName, you can call the Set* method on that object to set an object as the value of the specific property. For example, to set a new brush object as the background of a panel object, you would find that panel object in the visual tree, and then call IXRPanel::SetBackground.

If you are creating a UI element to be displayed on the GUI window, you must add it to the IXRUIElementCollection that belongs to the panel object that covers the window. Any UI element that inherits from IXRFrameworkElement can be added to this UI-element collection. This includes IXRUserControl, IXRContentControl, IXRTextBox, IXRItemsControl, IXRImage, and so on. To obtain a pointer to this collection, call IXRPanel::GetChildren.

To add this object to a collection, you can find a collection in the object tree, and then call IXRUIElementCollection::Add or IXRUIElementCollection::Insert.

To generate a separate visual host for this object, you can call IXRApplication::CreateHostFromElementTree.

.NET Framework Equivalent

None.

Requirements

See Also

Reference

IXRApplication::CreateObject
IXRApplication