IXRVisualHost (Compact 2013)

Article
04/19/2017

3/28/2014

This class hosts the visual tree of objects inside a Window (HWND) container so that the objects, both parsed from XAML and created in C++, can respond to events and window messages at run time.

Syntax

class IXRVisualHost :  public IUnknown

Methods

Method	Description
IXRVisualHost::DestroyWindow	Closes and destroys this visual host object.
IXRVisualHost::EndDialog	Closes and destroys the modal dialog created by using IXRVisualHost::StartDialog.
IXRVisualHost::GetContainerHWND	Obtains a handle (HWND) to the OS window that provides the foundation for this visual host.
IXRVisualHost::GetFocusedElement	Retrieves the element in the visual tree that currently has the UI focus.
IXRVisualHost::GetPosition	Retrieves the current on-screen position of this visual host.
IXRVisualHost::GetRootElement	Retrieves the top-level UI element in the element tree of the visual host.
IXRVisualHost::GetSize	Retrieves the size dimensions of the graphical window for the container of this visual host.
IXRVisualHost::HideWindow	Hides this visual host if it was previously displayed on the screen, and stops rendering the element tree.
IXRVisualHost::SetPosition	Sets the current on-screen position of this visual host.
IXRVisualHost::SetSize	Sets new size dimensions for the graphical window for the container of this visual host.
IXRVisualHost::ShowWindow	Shows this visual host if it was previously hidden, and renders its element tree onto the graphical window.
IXRVisualHost::StartDialog	Starts this visual host as a modal dialog box, which requires the user to supply information or dismiss the dialog box before the application can continue.

Thread Safety

Members of this class are thread-safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true.

Remarks

This class also supports the methods on the IUnknown interface.

By using a visual host, the system can interact with elements in the visual tree in the same way it interacts with window controls. The visual host contains an element collection in an underlying window container. You do not need to implement code for the WndProc of the foundational window. The visual host manages the WndProc of the foundational window and handles messages sent to the window, including dispatching them to the appropriate element in the XAML for Windows Embedded element tree. A visual host can contain only one element tree.

A visual host automatically handles relevant Win32 events on behalf of the client. For example, a visual host handles the following types of events:

Input events (input method editor (IME) events, key presses, stylus taps, and more).
Window resizing events.
Focus events (including moving the focus from background to foreground).
Interaction with other windows in the system.
Screen-rotation events.

Each IXRVisualHost object provides a pointer to an element tree. You can obtain the root element of that tree by calling IXRVisualHost::GetRootElement. That pointer represents the root object of the tree for that host, and is a pointer to an IXRFrameworkElement object. You can use the handle to the root element to add objects to the element tree, to modify objects in the tree, to render the objects on-screen, and so on.

IXRVisualHost also encapsulates the windowing functionality by containing a window handle (HWND) to an underlying window for the visual host. You can obtain the window handle by calling IXRVisualHost::GetContainerHWND. You can use the container window handle to use GWES functionality, such as calling the UpdateWindow method with the window handle as the parameter.

You can create an instance of an IXRVisualHost object by calling either IXRApplication::CreateHostFromXaml or IXRApplication::CreateHostFromElementTree.

When you create a class instance, use an IXRVisualHostPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

.NET Framework Equivalent

None.

Requirements

Header	XamlRuntime.h
sysgen	SYSGEN_XAML_RUNTIME